About Isigma (RESTful) Web Services

These are the general guidelines for Isigma Web Services that adhere to the REST (REpresentational State Transfer) conventions.

The API is defined as a series of RESTful web services in a Resource-Oriented Architecture (ROA). Isigma web services are thus based on standard HTTP mechanisms and their responses are typically in JSON or XHTML formats (the latter can be parsed as well-formed XML).

This kind of API has a low integration cost and can be used from any programming language that is able to generate HTTP requests and parse XML or JSON - this covers practically all modern general-purpose and web languages: Java, C# (and other .Net languages), Python, Ruby, Javascript, PHP, etc.

Conventions

General conventions for Isigma’s REST APIs:

• In general, all requests require a prior user authentication (see Authentication)

• HTTP requests behave uniformly with all resources by giving a uniform meaning to HTTP verbs:

  • GET: read,

  • POST: create,

  • PUT: update,

  • DELETE: erase data.

  GET requests normally don’t have side effects (do not modify the state of the resource) and are always idempotent (executing them multiple times has the same effect as doing it just once)

• The URL describes the route to the resource. When a URL description includes text between braces (e.g. {id}), it indicates that it is a variable part (e.g. in this case the database identifier of the resource)

• The data to be sent in POST requests is encoded as a standard web form. By default services use the encoding application/x-www-form-urlencoded (except in the cases where files must be uploaded, in those cases it uses multipart/form-data), and the character encoding UTF-8

• Parameters to GET requests are encoded in URL standard format as url?param1=value1;param2=value2.... These are used as modifiers to the request (e.g. data formats, pagination, filtering…) and not to define the route to the resource.

Authentication

Users are authenticated via the mechanisms already defined in HTTP, namely basic authentication as described in RFC-2617, by including the standard Authorization header in the HTTP request. Username and password must correspond with a registered user account.

We recommend using SSL in order to cipher the channel and not expose credentials (access the service at a URL starting with https://).

Data Format and Response Codes

Results of operations will be encoded with the HTTP response status (defined in http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html).

Sample typical results for Isigma Web Services:

HTTP Status	Description
200 OK	Successful execution. The response body contains the resource, except for DELETE, where it will be empty
303 See Other	Redirection to the resource page. This is a typical response after creating a resource with POST. The response header Location will point to the newly created resource
400 Bad Request	The request contains incorrect data (e.g. some form field is missing or has the wrong value or format)
401 Unauthorized	An attempt to access a resource from another user or with insufficient privileges
402 Payment Required	The operation requires an active subscription with available quota. It may also indicate a quota override (e.g. no more available signatures or disk space).
403 Forbidden	The operation is not allowed
404 Not Found	The referenced resource does not exist
405 Method Not Allowed	The HTTP method is not available for this resource (e.g. POST on a read-only resource that only allows GET)
409 Conflict	The resource cannot be created because a conflicting resource already exists (e.g. due to a duplicate unique field like a reference or id)
500 Internal Server Error	Internal error, possibly due to a software defect. Report these errors to Isigma.
503 Service Unavailable	The service is currently not available (e.g. due to maintenance)

Data returned by the API can typically be in formats JSON (MIME type: application/json) or XHTML (MIME type: application/xhtml+xml), except for specific download formats (e.g. PDF files: application/pdf). In order to force JSON format, Accept application/json header must be added.

XHTML documents have the advantage that they can be viewed in a browser (possibly by applying a CSS style sheet), and also be processed with an XML parser, e.g. using XPath expressions. In order to facilitate testing and service discovery, the API in XHTML format can be navigated: pages include hyperlinks to related resources, and resources that allow POST include HTML forms in their pages that can be used to that effect.

Date Representation

Dates are expressed in ISO8601 format (e.g. 2010-12-24T13:01:02+0100).