Communication model

User API communicates via HTTP (both POST and GET) protocol and provides many ways of communication JSON(P). Apart from general communication fields, that must be sent via POST/GET, all other data can be sent in any way. We strongly encourage the use of POST over GET method for sending data (except in the case of JSONP). All data sent via POST or GET should be URL encoded! 

The API can be tested in http://[server_address]/users/main/test_webapi2.html

Available fields (CGI parameters):

• method - method you wish to call. This field is mandatory!
• he - defines encoding of communication. By defining this setting, you define in what way would you like to receive response data from the API. Current version supports JSON1, CGI1. Default value is JSON1.
• ho - defines return encoding of communication. Current version supports JSON1. Default value is same as he.
• hl(or lang) - defines language. Value must be a ISO 639-1 code. Language defines the language in which response message should be returned. If message is not yet translated, English version will be returned.
• hs(or session_id) - defines web session id. The session is associated with some user. To get session id call webapi login. In case session id is used it must be valid or error will be returned.
• jsonp - In case JSON1 as ho field is specified the return will enveloped in function defined by jsonp.
• hedata - Input data of type he are normally sent in body of request. But in case of using jsonp (referencing script), some data might be needed. You can specify input data in this field.

Response objects: JSON1

JSON1 is version 1 of JSON response defined by ISL Online API protocol. Response object has following structure:

• result: this object hold all method result values/fields
  • description: translated message that can be shown to user in case of error
  • code: predefined message codes (look below)
  • errors: list of fields that failed in input data that caused the webapi call to fail
  • hs: in case the session token has been updated
• data: various data which is method specific

JSON1 structure:

json={

 "result" : {

         "description" : "generated description",

         "code" : "result_code",

         "errors" : {"key": "value pairs"},

         "hs" : "in case the session token has been updated"

 },

 "data" : "value" OR ["array", "of", "values"] OR { "returned": "value" }

}

API Messages

A part of response object is result code, which holds one of the predefined values:

Method executed without any exceptions:

• code: OK - all methods were executed without any problems.

User input/procedure errors (this is normal no need to fix implementation and usage of API - developer should handle this errors and show description to user):

• code: USER_ERROR

Usage errors (API developers did something wrong and should fix the error in module)

• code: IMPLEMENTATION_ERROR

Internal errors (something went wrong on server - core developers will fix this errors).

• code: INTERNAL_ERROR