REST headers and status codes

Include an HTTP header in a REST request to indicate the format of the request and allowed response, or to enable optimistic updating with ETag.

Response headers provide information about the status of the request, and return ETag information. The response also includes a status code.

HTTP defines a set of standard request and response headers. Use the headers to provide information about the entity or other resource that you are requesting. The Decision Server Insights REST API supports the following HTTP headers.

Request Headers

Headers

The REST headers and parameters contain a wealth of information that can help you track down issues when you encounter them. HTTP Headers are an important part of the API request and response as they represent the meta-data associated with the API request and response. Headers carry information for:

1. Request and Response Body
2. Request Authorization
3. Response Caching
4. Response Cookies

Other than the above categories HTTP headers also carry a lot of other information around HTTP connection types, proxies etc. Most of these headers are for management of connections between client, server and proxies and do not require explicit validation through testing.

Headers are mostly classified as request headers and response headers, know the major request and response headers. You will have to set the request headers when you are sending the request for testing an API and you will have to set the assertion against the response headers to ensure that right headers are being returned.

The headers that you will encounter the most during API testing are the following, you may need to set values for these or set assertions against these headers to ensure that they convey the right information and everything works fine in the API:

Request headers

Accept

Specifies the content types that are valid in the response message. If the server cannot respond with the requested content type, the 406 Not Acceptable HTTP status message is returned.

application/xml
application/json

Content-Type

Indicates the content type that is used in the body of the request. The supported content type is XML/Json.

application/xml
application/json

If-Match

Including If-Match in the header enables optimistic updating with ETag. The server checks to make sure that the entity version numbers match, then writes the entity and increments the version.

a8f34, or any string of characters that represents a specific version of the entity

If-None-Match

Including If-None-Match in the header enables optimistic reading of entities by using ETag. The server determines whether the ETag information matches when a GET request is processed. If the information matches, then the entity did not change since the last request. The server returns the HTTP status message 304 Not Modified and does not retrieve the entity. If there is not a match, the GET request is processed.

a8f34, or any string of characters that represents a specific version of the entity

Authorization

Carries credentials containing the authentication information of the client for the resource being requested.

WWW-Authenticate

This is sent by the server if it needs a form of authentication before it can respond with the actual resource being requested. Often sent along with a response code of 401, which means ‘unauthorized’.

Accept-Charset

This is a header which is set with the request and tells the server about which character sets are acceptable by the client.

Cache-Control

This is the cache policy defined by the server for this response, a cached response can be stored by the client and re-used till the time defined by the Cache-Control header.

Response headers

Allow

Lists the allowed request types for the solution or entity. If an invalid request is received, the HTTP status message 405 Method not allowed is returned.

GET - POST - DELETE - PUT

Content-Type

The MIME type of the response content.

application/xml

ETag

An alphanumeric string that represents the entity version.

a8f34, or any string that represents a specific version of the entity

Status

The Status line in the HTTP response indicates whether the server responded to the request successfully, or if there was an error.

200 - OK indicates a successful response
405 - Method not allowed indicates an error

Response status codes

200 OK: the request was successful.

201 Created: the request was successful, and one or more entities was created.

304 Not Modified: the entity was not updated, possibly because the ETag condition, such as If-Match or If-None-Match, stopped the request from completing.

400 Bad Request: the request was not properly formed and therefore was not successful.

404 Not Found: the URI path is incorrect, or communication with the server was unsuccessful.

405 Method Not Allowed: the syntax of the request does not match the request type. The Allow header provides more information about the supported types.

406 Not Acceptable: the Accept header response type is not supported. The supported types are XML and JSON.

409 Conflict: the entity or entities cannot be overwritten or deleted.

412 Precondition Failed: when the If-Match header is included in the request, this status indicates that the ETag information did not match and therefore the entity was not updated.

413 Request Too Large: the number of entities that is returned is too large.

415 Unsupported Media Type: the request contains a format that the server cannot interpret.

503 Service Not Available: the solution is not ready and could not respond to the request.