Response Format

Table of Contents

Response Body

In general every response from the API contains the following information, the default return type is XML, however JSON can be set by setting request Accept-Type header to “application/json”, see Request Format for samples.  The structure of the response body remains identical regardless of the response type.

Where the response is xml/json, the specific method is always wrapped with the following generic response which also provide status codes and error messages;

XML Response Type                      JSON Response Type               

xml</p><p>` `<Status>OK</Status></p><p>` `...result xml...</p><p></p><p>

javascript</p><p>{</p><p>` `"Status": "OK",</p><p>` `...result json...</p><p>}</p><p>

Note that both response types contain a consistent top-level element;
  • status - This contains information about the success or failure of the API call itself see Status Codes below

The content of each response type will always be identical and they are designed to be interchangeable, however there are two important differences between response types;

XML root node - as a well-formed XML document the response has a root node of , there is no equivalent to this in the JSON response.

Where there is an array of results, for example if multiple Job Statuses are queried in a single API call, then the XML response type will return multiple nodes with a singular name (i.e. ) whereas the JSON return type will return a plural array of results (i.e. “jobstatuses”:).

Reponses & Errors

All response codes are included in the HTTP Status response header, and in the element of a response. HTTP status codes values vary based on the type of operation, here is a summary;

GET Request - Possible Return Codes

HTTP Status CodeValueDescription
200OKSuccess
302FOUNDA common redirect response; you can GET the representation at the URI in the Location response header. (We will use this to allow us to make changes to the URIs and provide for redirection for old APIs).
304NOT_MODIFIEDYour client’s cached version of the representation is still up to date. (We may use this to support caching - needs technical investigation.)
400INVALID_CALLResource Invalid (improperly-formatted request)
401NOT_AUTHORIZEDUnauthorized (incorrect or missing authentication credentials)
404NOT_FOUND Resource Not Found (requesting a non-existent document, user, or other resource)
405NOT_ALLOWEDHTTP Method Not Allowed (e.g., trying to POST to a URL that responds only to GET)
406NOT_ACCEPTABLENot Acceptable (server can’t satisfy the Accept header specified by the client)
500APPLICATION_ERRORApplication Error
503SERVICE_UNAVAILABLEAny temporary error which prevents a response.  Essentially this code tells HTTP-Aware clients they should wait and try again later.

POST & PUT Request - Possible Return Codes

HTTP Status CodeValueDescription
200OKSuccess
201CREATEDThe request was successful, we created a new resource and the response body contains the representation.
400BAD_REQUEST Resource Invalid (improperly-formatted request)
401NOT_AUTHORIZEDUnauthorized (incorrect or missing authentication credentials)
404NOT_FOUND Resource Not Found (requesting a non-existent document, user, or other resource)
405NOT_ALLOWEDHTTP Method Not Allowed (e.g., trying to POST to a URL that responds only to GET)
406NOT_ACCEPTABLENot Acceptable (server can’t satisfy the Accept header specified by the client)
500APPLICATION_ERRORApplication Error
503SERVICE_UNAVAILABLEAny temporary error which prevents a response.  Essentially this code tells HTTP-Aware clients they should wait and try again later.

DELETE Request - Possible Return Codes

HTTP Status CodeValueDescription
200OKSuccess
401NOT_AUTHORIZEDUnauthorized (incorrect or missing authentication credentials)
404NOT_FOUND Resource Not Found (requesting a non-existent document, user, or other resource)
405NOT_ALLOWEDHTTP Method Not Allowed (e.g., trying to DELETE to a URL that responds only to GET)
406NOT_ACCEPTABLENot Acceptable (server can’t satisfy the Accept header specified by the client)
500APPLICATION_ERRORApplication Error
503SERVICE_UNAVAILABLEAny temporary error which prevents a response.  Essentially this code tells HTTP-Aware clients they should wait and try again later.

In our API every resource representation obtained from a REST API request must include URIs that identify that resource and the resources related to it. This allows for clients to traverse resources very easily without complete knowledge of the API structure - this is important for Aspose for Cloud since parts of our REST structure will be dynamic.

List Resources & Resources (with Sub-Resources)

Where we have sub-resources we will use ATOM links to specify the URI for the sub-resource.  For version 1.0 of the REST API where a sub-resource is a collection (i.e. a list resource) we will not list the children in the parent resource, but simply have a link to the List sub-resource.  In a future version we may provide parameters which support “expansion” of sub-resources so that more information can be retrieved in a single request.  Here is a simplified example of each;

In this version clients will need to make a subsequent request to the specific sub-resource to actually get the list of pages, we do not pull in any summary information about the pages into the document resource.