REST API: Introduction

A REST API is an API based on HTTP and JSON.
XStudio's REST API is a complete set of APIs (more than 400 methods) allowing to control/drive any action programmatically on XStudio.
Everything you can do with XStudio.web you can do it programmatically also.

REST

REST-style architectures consist of clients and servers. Clients initiate requests to servers and servers process requests and return appropriate responses. XStudio REST API's requests and responses and encoded in JSON.

JSON

JSON (JavaScript Object Notation), is a text-based open standard designed for human-readable data interchange. It is used primarily to transmit data between a server and web application, serving as an alternative to XML (but much lightweight).

Basics of the APIs

All the responses are returned through HTTP formatted as a JSON message.

For instance, you can browse the URL:
http://<server>:8080/xqual/api?command=getInfo
https://<server>:8443/xqual/api?command=getInfo (if your server has SSL enabled)

You can also use the alternative form without 'command':
http://<server>:8080/xqual/api/getInfo
https://<server>:8443/xqual/api/getInfo (if your server has SSL enabled)

This will return a JSON string similar to:
Most of the methods require the user to be authenticated first (see the authenticate method.
When you authenticate, a session cookie ("JSESSIONID") is created and returned by the server to maintain a unique session for this user. The client must insert this cookie in all the subsequent call to the REST API server. In addition, many methods (those for creation, update and deletion mostly) require to be sent in a POST http request (as opposed to GET).
Here is the source of Java example client, authenticating to a XStudio REST API server, retrieving a few information and finally creating a requirement.

An API will be executed and will return a success only if the authenticated user has the right to call it. This is based on the rights set to the user through his/her user profile.

Errors returned

In case of error the response includes a status indicating the source/reason of the error.
It can be:

200 (HttpServletResponse.SC_OK) in case of success
400 (HttpServletResponse.SC_BAD_REQUEST) for instance when wrong parameters are passed to the methods
403 (HttpServletResponse.SC_FORBIDDEN) when the user has not sufficient rights to perform the command
404 (HttpServletResponse.SC_NOT_FOUND) when the method detects an error itself
500 (HttpServletResponse.SC_INTERNAL_SERVER_ERROR) when the code has badly crashed

Some more details may be passed in the json itself.
i.e. in case of error 403 the json message will be similar to:

Important note on returned arrays

Many of the following methods returns arrays. In some cases, the arrays can contain only 1 element. In this case, the returned JSON will not include an array but a single child. The client is responsible to manage that for example with a code like, this:
if (!$.isArray(this.xxx)) {
   this.xxx = [this.xxx];
}
When it expects an array element and it isn't one, it simply put it in an array.