Communication model

User API communicates via HTTP protocol and provides 3 ways of communication (POST/GET, JSON(P)). Apart from 4 general communication fields, that must be sent via 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! 

Available fields:

• 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. This field is mandatory!
• hl - 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.
• hc - defines country. Value must be a ISO-3166-1 Alpha-2 code. Country setting defines country specifics that API might have.

Response objects: JSON1

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

• method: which method was called
• response: the response values
      - result: this object hold all method result values/fields
          - description: translated message that can be shown to user
          - code: predefined message codes (look below)
          - args: arguments which correspond to message code; it can be in a following formats:
             - key-value pair: "data": "returned data value"
             - array: "data": ["array", "of", "values"]
      - data: various data which is method specific; it can be in any JSON valid format:
          - key-value pair: "data": "returned data value"
          - array: "data": ["array", "of", "values"]
          - object: "data": { "returned": "item" }

JSON1 structure:

 json={ 
   "method" : "method_name", 
      "response" : { 
        "result" : { 
           "description" : "generated description", 
           "description_orig" : "generated non-translated description", 
           "code" : "result_code", 
           "args" : "argument_key" OR ["array", "of", "arguments"] 
        }, 
        "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 (developer did something wrong and should fix the error by reading documentation and following samples)
  code: IMPLEMENTATION_ERROR
• Internal errors (something went wrong on server - API developers will fix this errors. When spotted they should be reported back to support@islonline.com)
  code: INTERNAL_ERROR