JSON API lets you integrate any external tool with Collaborator. To do this, you need to exchange data between your application and your Collaborator server. To use the web service you need to send requests to web service endpoint URL and receive responses from it. The service receives and sends data in JavaScript Object Notation (JSON). For detailed information on JavaScript Object Notation, see JSON Syntax and Data Formats.
Endpoint URL
The web service resides on your Collaborator server at the following endpoint URL:
http(s)://yourServer.com/services/json/v1
Using JSON API Web Client
To get acquainted with service requests and responses, you can open the endpoint URL in a web browser. It will display a simple form, where you can write JSON commands and get service responses within the same page.
Let us try to call some JSON commands manually:
-
Open a web browser and navigate to JSON API web service URL:
http(s)://yourServer.com/services/json/v1 -
Enter the following command into the input field:
[
{"command" : "ServerInfoService.getVersion"},
{"command" : "Examples.echo","args" : {"echo" : "Some text."}}
]
-
Press Submit Query button.
After the page is reloaded you will get the response from the service with the results of your commands:
[ {
"result" : {
"version" : "9.0.9000"
}
}, {
"result" : {
"echo" : "Some text."
}
} ]
Later on you can use JSON API web interface to try and debug JSON commands manually before sending them programmatically from your client application.
Using JSON API From Client Applications
The client and server exchange data in the JSON format via HTTP(s) requests and responses. Client application must send POST requests to JSON web service endpoint URL. The requests should contain a JSON object in their body or in the POST variable named "json". For multipart requests the JSON object must be either in a "json" string part or in a "json" query parameter.
A JSON object in a request specifies a list of commands to be executed and arguments for these commands.
Here is an example of a POST request:
POST http://yourServer.com/services/json/v1 HTTP/1.1
User-Agent: JSON API
Content-Type: application/json;charset=utf-8
Host: yourServer.com
Content-Length: 138
[
{"command" : "ServerInfoService.getVersion"},
{"command" : "Examples.echo","args" : {"echo" : "Some text."}}
]
A multipart variant of the same request will be:
POST http://yourServer.com/services/json/v1 HTTP/1.1
Content-Type: multipart/form-data; boundary=-------------------------acebdf13572468
User-Agent: JSON API
Host: yourServer.com
Content-Length: 265
---------------------------acebdf13572468
Content-Disposition: form-data; name="json"
Content-type: text/plain;charset=utf-8
[
{"command" : "ServerInfoService.getVersion"},
{"command" : "Examples.echo","args" : {"echo" : "Some text."}}
]
---------------------------acebdf13572468--
On receiving the request, the server processes each command in order and builds up a response. The JSON object in response contains a list of results corresponding to each of the command that you submitted. Each result consists of either the return values for that command, or a list of errors returned by the command. See Error Handling.
The response to any of the requests above will be:
HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
Content-Type: application/json;charset=utf-8
Content-Length: 68
Date: Thu, 27 Nov 2014 10:55:25 GMT
[{"result":{"version":"9.0.9000"}},{"result":{"echo":"Some text."}}]
In further examples of this section, we will omit request and response headers (when their content is not important) and give only the examples of JSON parts.