Explains urls, HTTP headers, status codes, way of returning error codes, caching and data consistancy.

Before reading this article we recommend you to read Terms, Security and Error handling.

The background protocol is regular HTTP. Follow regular REST convention to understand API architecture. Here is a few important points you must know:

• Response body is returned according to Accept header when no error occurs. It should be “application/json” for JSON and “application/javascript” for JSONP.
• List of all available url’s for data exchange with description and code samples can be found at JSON-REST Reference .
• And don’t forget to declare Content-Type: application/json when sending data to the server.

Url naming conventions

General format of every url is

https://servername.com/vversion/collection-name[options]

where

• servername.com will be provided to you by support team
• version is a number of current api version, you can find this number by visiting https://servername.com/api/version, and get all the info (documentation, examples and libraries) about it at http://srv4pos.com/vversion. For instance if version is 15, then the url will look like https://servername.com/v15/collection-name[/options], the info about it is reacheable at http://srv4pos.com/v15
• collection-name is the name of entity, for instance all products can be found by url https://servername.com/v15/products
• options might be
  • /identifier
    to reach particular entity. for instance to reach product with identifier “0-1A9E” you use https://servername.com/v15/products/0-1A9E
  • -diff/from/to
    to discover, what has been changed on the server. for instance, if you want to know which products have been deleted, created or modified between 100 and 200 you use https://servername.com/v15/products-diff/100/200 . If you are interested what is 100 and 200 – read Synchronization and Caching
  • /identifier/images
    to see which images are attached to a particular entity. for instance https://servername.com/v15/products/0-1A9E/images will show list of all images for product with id 0-1A9E
  • ?firstResult=0&maxResults=30&orderBy=fieldName&orderDesc=false&like=substring to be able to narrow output results. Each parameter is optional. Some parameters might not work under some urls. There can be some more parameters

This is just a convention, and some urls don’t follow it.

Other notes:

• Words are separated with hyphens (‘-‘) and lower case: https://servername.com/v15/control-units
• GET, DELETE, PUT http methods are allowed for https://servername.com/vversion/collection-name/identifier
• POST to https://servername.com/vversion/collection-name creates an entity
• This convention was taken from
  http://www.restapitutorial.com/lessons/restfulresourcenaming.html

Authentication

Most of the URLs requires authentication. Basic authentication is used. Use “Authorization” header. Value is word “Basic ” and base64 encoded string. The string depends on your role:

• For role ACTIVATION the string is:
  {sellerId}/{productionNumber}:{activationSecurityToken}
• For role SELLER_ADMIN the string is:
  {username}@{sellerId}:{password}

Error handling

For simple json exceptions:

{"error":"SomeSimpleJsonException"}

1 {"error":"SomeSimpleJsonException"}

For detailed json exceptions:

{ "details":{ "identifier":"ID-1", "entityName":"MyEntity" }, "error":"SomeDetailedJsonException" }

1 2 3 4 5 6 7 { "details":{ "identifier":"ID-1", "entityName":"MyEntity" }, "error":"SomeDetailedJsonException" }

For special ValueNotValidJsonException:

{ "details":[ { "code":"SPECIFIC_ERROR_CODE", "field":"name", "message":"Some message.", "params":{ "actualValue":"invalidValue", "someParam1":"1", "someParam2":"32" } } ], "error":"ValueNotValidJsonException" }

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 { "details":[ { "code":"SPECIFIC_ERROR_CODE", "field":"name", "message":"Some message.", "params":{ "actualValue":"invalidValue", "someParam1":"1", "someParam2":"32" } } ], "error":"ValueNotValidJsonException" }

For UnprocessableJsonException, InconsistentDataJsonException and ForbiddenJsonException:

{ "code":"SPECIFIC_ERROR_CODE", "details":{ "message":"Some message" }, "error":"SomeSpecialJsonException" }

1 2 3 4 5 6 7 { "code":"SPECIFIC_ERROR_CODE", "details":{ "message":"Some message" }, "error":"SomeSpecialJsonException" }

The field “error” contains name of json exception.

The field “code” contains specific code of error. It can be used for localization and so on.

List of all JsonExceptions and types of error (codes) presented in the here.

Caching

Some GET methods support ETag header. When returning data they return seller version inside ETag. Seller version and principles are described at Synchronization and Caching page. Later you can provide If-Match to the methods so they may return HTTP status code 304 and no body, Which means the data was not modified since the seller version specified in ETag.

Date & time

All data & time is always in UTC.

Data consistancy

If your role is ACTIVATION then POST, PUT, DELETE methods require you to provide latest seller version (to make sure the version is actually latest). Provide it in If-Match header. If you want to know more about Data consistancy, read Synchronization and Caching page.