Adelya Object Reference

Objects, Operators and Error codes

Objects

Operators

For non exact queries see :Operators

Error Codes

List of most common error codes :Error codes

Some diagrams...

...worth a thousand words

Formats, norms, encoding

Please note that due to compatibility requirement with previous version, we slightly transgress the common REST rules on 2 points : 1/ GET and POST are equivalent (both retrieve the data), 2/ the URL is always the same for any object type and id is part of the posted data.

POST/PUT/DELETE BODY Encoding : Post body is intended to be as-if posted by an HTML form, so a Content-Type of : application/x-www-form-urlencoded is expected. If this is not respected decoding parameters may fail

Otherwise stated, everything should be encoded in UTF-8

default length for AlphaNumeric data fields is 127 characters

Country code follow the ISO 3166 (2 letters, e.g. : FR)

Languages code follow the ISO 639-1 (2 letters, e.g. : de for german)

Phone numbers follow the E.164

Dates :

  • Dates returned follow the ISO 9075 in the CEST timezone (e.g : '2013-12-25 00:00:00' for 2013 xmas), but you can add the parameter dateformat=iso8601 to change them to iso8601 extended.
  • Dates in API call can be either ISO 9075 (in CEST TZ) or ISO 8601 extended with or without ms (e.g. '2020-11-30T15:31:00-06:00' or '2020-11-30T15:31.000:00-06:00' or '2020-11-30T21:31.000:00Z')
  • Dates in API are different from datetime. In general, validity periods on our objects are from date format and are set on our side
    • Start date : set to start of the date's day (00:00:00)
    • End date : set to end of the date's day (23:59:59)
    • If a datetime is provided it will be converted to server timezone. If the target field is a date field, it could result some date shifting
    • In API return, even a date field is returned as datetime

otherwise stated, data retrieval is case insensitive. (e.g. searching for member firstname 'john' or 'John' will returned the same set of data)

Return data subset

The quantity of data returned can be overwhelming. You can use the fields parameter to specify the fields of the main object to be returned

This work for single or list returned data.

Example GET Customer basic fields : GET /apiv1/webapi.do?json_data={CompactFidelityMember:{actif:"1"}}&fields=name,firstname,mobile

note : Apiv2 (in Alpha status) use graphQL to achieve a more complete result

Return the persisted object

When you persist an event or a member the business rules are run and may modified the object itself. It is quite common to want to have a look at the modified data (e.g. for synchronization purpose). Of course you can chain a PUT and a GET, but we provide a shortcut, to limitate the number of interactions. add the returnType=show parameter to your url.

You will have a data node part of the response containing the object data.

Example GET Member info after persist : PUT /apiv1/webapi.do?json_data={FidelityMember:{actif:"1",name:"dujardin"}}&returnType=show return : { "ApiReturn":{ "code":"OK", "message":"Everything went ok !", "data":{ "FidelityMember":{ "id":"11299822", "dateUpdate":"2019-07-30 16:02:43", "idExternals":"", "defaultLanguage":"", "type":"C", "src":"C", "name":"DUJARDIN", ... } }, "id":"11299822" } }

note : returnType and fields parameters cannot be combined

Translations

Some entities are translatables. Translatables entities :

  • Group
  • Catalog
  • Item
  • Category

API access to translations only work for single entity.

Return object translations

You can use the locale parameter to specify the target translation to be returned. locale can take 3 kinds of values :

  • <empty>: get pure object, without specific translation
  • *: get all specified translations inside translationList node
  • <LOCAL>: get the native object with translated fields
Example GET Catalog with translated fields (for english language) : GET /apiv1/webapi.do?json_data={Catalog:{uniqueId:"6587dea8-7681-11e7-86fa-4a49434984bf"}}&fields=descr&locale=en return : { "Catalog":{ "id":11969, "descr":"TestCache US" } }
Example GET Catalog with all translated fields (for all language) : GET /apiv1/webapi.do?json_data={Catalog:{uniqueId:"6587dea8-7681-11e7-86fa-4a49434984bf"}}&fields=descr&locale=* return : { "Catalog":{ "id":11969, "descr":"TestCache", "translationList":{ "descr":{ "fr":"TestCache FR", "en":"TestCache US" } } } }

Set object translations

Each translatable fields can be specified in the translationList node, with the tagret <LOCALE> (as sub-node) for this translation.

Example SET descr on Catalog (for spanish language) : { "Catalog":{ "id":11969, "descr":"TestCache FRance", "translationList":{ "descr":{ "fr":"TestCache FR", "es":"TestCache ES" } } } } Return { "ApiReturn":{ "code":"OK", "message":"", "id":"11969" } }