All data-interchange with the service is performed in JavaScript Object Notation (JSON).
JSON uses two data structures: a collection of name/value pairs and an ordered list of values. JSON engine ignores whitespace, tabulation, and newline characters, however you can use them to improve readability.
JSON Objects In Requests
A JSON object that is sent in web service requests (request object) specifies a list of commands to be executed and arguments for these commands.
The simplest variant of a JSON request object is:
[
{"command" : "MethodName1"}
]
The "command" : "MethodName1" pair defines which command a server should run. The method name is specified using dot notation. For example "ServerInfoService.getVersion", or "Examples.checkLoggedIn".
If a method needs some arguments, then you will need to add the "args" : { } pair which specifies a list of arguments:
[
{"command" : "MethodName1",
"args" : {"argumentName1":"value1","argumentName2":"value2",..."argumentNameN":"valueN"}
}
]
The "argumentName" : "value" pairs define argument names and their values. A value can be a string in double quotes, or a number, or true or false or null, or an object or an array. When a method needs more then one argument, the "argumentName" : "value" pairs are separated by commas. Argument pairs can be specified in any order.
You can create batch commands, that is, pass several commands in one JSON request object. Different commands should be separated by commas. For example:
[
{"command" : "ServerInfoService.getVersion"
},
{"command" : "Examples.echo",
"args" : {"echo" : "Some text."}
},
{"command" : "SessionService.setMetadata",
"args" : {
"clientName" : "HTML JSON API Tester",
"expectedServerVersion" : "9.0.9000"
}
}
]
JSON Objects In Responses
A JSON object that is received in web service responses (response object) contains a list of results corresponding to each of the command that was submitted. Each result consists of either the "result" : { } pair that lists the command return values (if any), or the "errors" : [ ] pair that lists the errors returned by the command. (See Error Handling for details).
Results for several commands that were passed in a single JSON request object are returned as a comma separated list. For example the response object for the previous request will be:
[
{ "result" : { "version" : "9.0.9000" } },
{ "result" : { "echo" : "Some text." } },
{ "result" : { } }
]
Date and Time Format
To specify date and time values, use strings having the format "YYYY-MM-DDTHH:mm:ssZ". For example: "2008-01-01T22:50:00Z" or "2008-01-01T16:50:00-06:00".
The table below describes the parts of this format.
| Part | Description |
|---|---|
|
YYYY |
Year |
|
MM |
Month |
|
DD |
Day of the month |
|
T |
Specifies the start of a time notation. |
|
HH |
Hours |
|
mm |
Minutes |
|
ss |
Seconds |
|
Z |
Time zone. The value in this position can be one of the following: Z - indicates UTC time. +hh:mm - indicates that the input time is the specified offset after UTC time. -hh:mm - indicates that the input time is the absolute value of the specified offset before UTC time. |