Request and Response Formats

Request Format

Request Headers

Content Types

The REST API uses content types to determine which version of an API should be used. REST methods can return data in multiple formats. The API determines which version is to be used through content types in the HTTP headers in the request, which allow the requester to indicate the format of the data that they are providing (if any), and the format they would like to receive the results.

The required HTTP headers are:

• Content-Type – indicates the format of the data sent by the requester.
• Accept – indicates the expected format of the response.

If the request includes input data but no Content-Type header, the REST API could misinterpret the request by incorrectly determining its type; if there is response data but no Accept header in the request, then the REST API chooses a default response type (normally text/html which renders in a web browser).

Typically, the REST API expects either no input parameters, or a text/plain or application/json parameter. On output it returns either no data (with a 204 No Content response code), text/html, application/json, or text/plain. An automated tool calling the REST API should use either the application/json or text/plain result types as these are designed to be machine readable.

Content types can be provided when using cURL by setting the -H parameter, which is set once for each HTTP header to be included:

curl -v -b cookies.txt -c cookies.txt --cacert myCert.cer -X PUT -H "Content-Type: text/plain" -H "Accept: application/json" -d "21345" https://server:8444/api/someApiMethod

• -H: Sets the two HTTP headers.
• -d: Sets the input data for the request (which must be formatted in the format stated by the Content-Type header).
• -X: Sets the type of HTTP method being called which in this case is a PUT (it defaults to GET if not specified).

Cross Site Request Forgery Protection

Cross Site Request Forgery (CSRF) is a form of malicious exploit where an unauthorized command is (unknowingly) transmitted by a user that the web server already trusts, effectively allowing an unauthorized user to make changes to the web server by utilizing the session of the authenticated user. Details and examples of CSRF attacks can be found at:

• Cross-Site Request Forgery (CSRF).
• Cross-site request forgery.

Rhapsody prevents CSRF attacks in its web tier through the use of a CSRF token which is randomly generated for each HTTP session that is established (effectively a large random number that is Base64-encoded). This CSRF token must be included in HTTP requests that attempt to modify data, such as PUT, POST or DELETE, from the second request onward. The first request that creates a new session is authenticated using the username and password provided in the Authorization header. The CSRF token must be included in all subsequent PUT, POST or DELETE requests.

A CSRF token is not required for GET, HEAD, TRACE, or OPTIONS requests, as these only read data and are not vulnerable to CSRF attacks.

The CSRF token is made available to requesters in all HTTP responses in an HTTP header called X-CSRF-Token. It must be subsequently provided in all PUT, POST, or DELETE requests using one of the following methods:

• Set an HTTP header called X-CSRF-Token that includes the token (the preferred approach whenever possible).
• Provide it as a query parameter called CSRFToken in the request URL (for example, https://server:8444/api/someMethod?CSRFToken=asdhjk78awd8123asd/ads13=).
• Provide it as a form parameter called CSRFToken if the REST method expects form data to be provided.

Failure to include the correct token results in the request being rejected with a 400 Bad Request status code and an error message indicating that the CSRF token was not provided.

The CSRF token does not need to be included on the initial request that establishes a new session (and an incorrect CSRF token is ignored in this case) because the fact that a new session has just been established (and authenticated) means that session-riding cannot yet be taking place.

Request Body

Various parameters can be passed through the Request Body depending on the type of REST API method. Refer to Monitoring REST API Methods for details.

Response Format

The default return type is HTML. An HTML content type is also available to provide a simple rendering of the returned data. The HTML response is primarily intended for testing purposes (both for internal testing, and for user testing of API functionality).

The primary return type from each API method is JSON or plain text for simple strings (except for those operations returning no content).

HTTP Response Status Codes

Standard HTTP response codes are used to indicate the type of response. In particular, 200 OK is used for successful requests; 204 No Content is used when when no content is returned.

Error responses are 4xx for errors in the incoming request and 5xx for server side errors. In some cases, JSON responses are still available in a 4xx/5xx response and may contain error information, particularly in the case of validation errors.

Requests typically use the following response codes:

Response Headers

Response Headers contain the standard HTTP response header fields.

Response Body

The JSON responses follow a standardized pattern containing two top-level fields:

• data – the response data which may be a primitive, array, hash, or null depending on the type of request.
• error – any error that occurs performing the request.
  • code – a generic error code describing the error at a high level.
  • messages – a list of error messages describing the problems that have occurred.

All display strings are translated prior to sending the response using the locale specified in the incoming request or the default Rhapsody locale if the requested locale is unavailable or not specified.

Response Errors

The format of errors returned from a REST API method depend on the Accept Request Header:

For example, a typical error response for a JSON request would appear as follows:

{
    "data":null,
    "error":
    {
        "code":"ERROR_CODE",
        "errorFields":["errorField1", "errorField2"],
        "messages":["message1", "message2"],
        "invalidFields":["invalidField1", "invalidField2"]
    }
} 

where:

• data is the data returned from the REST API.
• code is a string with the error.
• errorFields is a list of strings.
• messages is a list of strings.
• invalidFields is a list of strings.