HTTP Response

Status Codes

Every valid HTTP request receives a response that is comprised of three main components:

A 3-digit response status code that gives information about the success or failure of the request, the returned content, and other information specific to the request.

(2) The response header(s), which vary by request. These headers contain metadata information about the request, the response, the response data, and/or attributes of the server.

(3) The response body where free-form text information can be returned to the requester in either JSON (default) or XML format and in a standard defined by the application. This is where application-specific data pertaining to representation, success, and errors is returned to the requester.

Comprehensive list of HTTP status codes: https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html

Lgfapi uses many of the available HTTP response status codes to convey success or failure of the request back to the user. All response status codes fall into 1 of 4 categories:

1xx – Informational

2xx – Success

3xx – Redirection

4xx – Failure

The following is a list of commonly used response status codes for lgfapi:

Status Code	Status Message	HTTP Method	Description
200	Ok	HEAD, GET, POST	GET - The request was successful. HEAD - The resource exists. POST - Resource exists and/or has been modified.
201	Created	POST	Resource successfully created.
204	No Content	POST	The request was successful, but no content is being returned in the response body.
304	Not Modified	HEAD	The resource has not been updated since the target date-time.
400	Bad Request	HEAD, GET, POST	Invalid data or request structure.
401	Unauthorized	HEAD, GET, POST	Invalid login credentials.
403	Forbidden	HEAD, GET, POST	User lacks permission.
404	Not Found	HEAD, GET, POST	The resource does not exist.
405	Method Not Allowed	-	HTTP method is not supported for the requested resource.
409	Conflict	HEAD, GET, POST	Record Changed - The resource was modified by a concurrent operation before the request could be fulfilled. Try again.
500	Server Error	HEAD, GET, POST	An unhandled error occurred or the application was unable to formulate a valid response. Please contact support and provide any returned error information.

Response Formats

Lgfapi supports JSON (default) and XML formats for data returned in the body of the response. This applies to all HTTP methods that return a response body.

The requester is able to specify the response format in several ways:

Making a request without specifying the response format will result in the default JSON format.
Using the reserved “format” query string parameter in the URI when making a request.

You can set the format to XML by adding “format=xml” to the query string portion of the request (the key-value pair data after the “?”). This is in addition to any other query string parameters also in the URI:

…/resource/?format=json

…/resource/?format=xml

Note – “format” is one of the few query string parameters you can use with HTTP methods like POST, which typically require all data to be in the body of the request.

Using the file-extension dot-notation in the URI when making a request.

Very similar to the example above, you can also request the format using dot notation like you would when giving a file the extension “.xml” or “.json”:

…/resource/.json

…/resource.xml (optional trailing slash)

This can also be combined with a query string:

…/resource/.xml?key1=value1&key2=value2

Response Data Encoding

When a response body is returned, the raw JSON or XML data will always be encoded using UTF-8. There is no way to configure or specify the response body’s encoding. This is done to ensure that the response content can always be correctly rendered. A request body using a different encoding is allowed because the requester is able to control the contents being sent to lgfapi. However, the output data may contain characters outside of the encoding used for the request, if for example a consistent character set has not been used throughout the application. UTF-8 covers the full change of characters supported by OCWMS and is therefore the default, and generally preferred, encoding.

Response Data Formats

In general, the HTTP response body can take on any number of different formats and styles. For lgfapi, several dedicated conventions have been adopted to give uniformity and consistency to the handling of both successful and erroneous requests.

Error Response

A standardized error format is returned in the body of the response whenever there is an error while fulfilling the request. This is accompanied by the response status code, which provides additional insight.

The standard error response is comprised of 4 components:

Reference – A unique string used as reference for the request and error. This should be provided in support requests to help more quickly identify the information pertaining to the request in question.
Code – A generic classification pertaining to the error message.
Message – An error message related to the code.
Details – Optional. Either a list or key-value map (dictionary) of more detailed information pertaining to the error(s). For example, this may give a more detailed list of error messages or could be a map of field name(s) to error(s).

Example JSON Error Response Body:

{

"reference": "25b414f0-7a1d-4f35-ac3c-0ec9886cf37a", "code":
        "VALIDATION_ERROR",

"message": "Invalid input.", "details": {

"reason_code": "Invalid Reason code"

}

Example XML Error Response Body:

<?xml version="1.0" encoding="utf-8"?>

<error>

<reference>25b414f0-7a1d-4f35-ac3c-0ec9886cf37a</reference>

<code>VALIDATION_ERROR</code>

<message>Invalid input.</message>

<details>

<reason_code>Invalid Reason code</reason_code>

</details>

</error>

Unhandled Errors

It is possible that the application is unable to convey the nature of the problem back to the requester. In these scenarios, the server will respond with a 500 (“Server Error”) status code and an accompanying message.

Resource Representations

Representations are by default paginated unless a specific resource is being requested. Pagination allows the response data to be served in chunks (pages) to keep payload sizes manageable.

Pagination

A paginated result set is returned when multiple representations may exist in the result set that exceed a preset size. This breaks the result set into chunks (pages), each with its own page number. The page size is determined by the requesting user’s configuration of the field “Rows per Page”. This is the same field used to set the number of results per UI page returned. It has an allowed range of 10 to 125 results per page.

Pagination Mode

Two modes of pagination are supported that offer different advantages and disadvantages depending on the user requirements. The default mode is “paged”, but users may specify the type of pagination by using the “page_mode” query string parameter in the URI. The two types are “paged” and “sequenced”.

Mode: Paged

This is the default mode for result sets (…/resource/?page_mode=paged). This will break the data into chunks (pages) and return one page per request. This will additionally return metadata such as the total count of results and the total number of pages.

Each page of the result set is given a pagination header:

result_count – The total number of results across all pages.
page_count – The total number of pages.
page_nbr – The current page number.
next_page – Hyperlink to the next page (if available).
previous_page – Hyperlink to the previous page (if available).
results – The result set list for the page.

A specific page number for a paginated result set is requested in the URI’s query string using the parameter “page”. For example, to request the data for page 3 of a result set, one would add …/resource/?page=3. You will also see these automatically added in the hyperlinks generated for “next_page” and “previous_page”.

An example of a paginated JSON response:

{

"result_count": 1,

"page_count": 1,

"page_nbr": 1, "next_page": null, "previous_page": null, "results":
      [

{

"id": 0,

…

},

]

}

An example of a paginated XML response:

<?xml version="1.0" encoding="utf-8"?>

<entity_name>

<result_count>1</result_count>

<page_count>1</page_count>

<page_nbr>1</page_nbr>

<next_page></next_page>

<previous_page></previous_page>

<results>

<list-item>

<id>0</id>

…

</list-item>

</results>

</entity_name>

Mode: Sequenced

The sequenced mode (…/resource/?page_mode=sequenced) is similar to the Paged mode, except for a few important details. This mode is recommended for system to system integration where superfluous information and intuitive/human-readable values are not necessary.

Each page of the result set is given a header that conveys extra information to the user and makes it easier to navigate between pages:

next_page – Hyperlink to the next page (if available).
previous_page – Hyperlink to the previous page (if available).
results – The result set list for the page.

First, you’ll notice that the pagination header does not have the total result count or total page count. This is because sequenced pagination doesn’t know either of these values, and doesn’t want to. Instead, each page is generated on the fly in an effort to improve performance, which means less work than paged mode where the total counts are fetched up front. Determining total count can be expensive when you have a large result set.

With sequenced, you also sacrifice some human readability and functionality as the “page” query string parameter is replaced by a system-generated “cursor” as well as the hyperlinks will not be as intuitive to understand. Since in this mode the total result set is not known, only what’s rendered per page, there is no way to report the total number of pages or label each with a specific page number. A cursor identifier is generated for each page instead of a page number:

…/resource/?cursor=cD0xNDAw&page_mode=sequenced

Non-Paginated Responses

There are a few scenarios where a request will return data in the body of the response for a specific object, so pagination is not needed.

The first is for a GET retrieve style request where the “id” value of the resource is known and is requested in the URI (…/resource/{id}/).

The second is when creating a single resource using a POST request. The response will be a non-paginated representation for only the new resource.