Requests and responses

The OpenText Core Software Delivery Platform REST API uses standard HTTP methods and exchanges data as JSON. This topic describes the conventions that apply to every request and response.

HTTP methods

The API maps HTTP methods to operations on resources:

Method	Operation
`GET`	Retrieve a collection of entities, or a single entity.
`POST`	Create one or more entities.
`PUT`	Update one or more existing entities.
`DELETE`	Delete one or more entities.

The methods that a given collection supports are determined by its metadata; not every method is available for every collection.

You can also act on several entities in a single request. To create or update multiple entities, send an array of entities in the request body. To update or delete multiple entities that match a condition, send the request to the collection with a query parameter that selects them. For details, see Filtering.

Note: If your HTTP client cannot send a particular method, you can send a POST request and set the X-HTTP-Method-Override header to the intended method, such as PUT or DELETE.

Request headers

The following headers apply to API requests. Host and Cookie are required on every authenticated request; the others apply when relevant:

Header	Description
`Content-Type`	Set to `application/json` when the request has a JSON body.
`Accept`	The media type you expect in the response, typically `application/json`.
`Accept-Encoding`	Set to `gzip` to receive a compressed response. See Response compression.
`Cookie`	The session cookie received at sign-in. See Authentication.
`Host`	The server host, as required by HTTP.
`ALM-OCTANE-TECH-PREVIEW`	Required when calling a tech-preview resource; omit for standard resources. Set its value to `true`.

Response headers

The following headers appear in API responses:

Header	Description
`Content-Type`	Present on all responses that include a body. The value is typically `application/json`.
`Content-Encoding`	Present as `gzip` when the response body is compressed. Only returned if you sent `Accept-Encoding: gzip`.
`Date`	Present on all responses. The date and time the response was generated.
`Set-Cookie`	Returned only by the sign-in response, carrying the session cookie.

Response compression

The API can return compressed responses. Request compression by sending Accept-Encoding: gzip; the server then sets Content-Encoding: gzip on the response. Only gzip is supported.

Response status codes

The API uses standard HTTP status codes to report the outcome of a request. The following are the most common:

Status	Meaning
`200 OK`	The request succeeded. Returned for read, update, and delete requests.
`201 Created`	Entities were created successfully.
`400 Bad Request`	The request was malformed or contained invalid data.
`401 Unauthorized`	Authentication is missing or the session has expired.
`403 Forbidden`	The caller is authenticated but not permitted to perform the request.
`404 Not Found`	The resource or entity does not exist.
`405 Method Not Allowed`	The HTTP method is not supported by the resource.
`406 Not Acceptable`	The requested media type cannot be produced.
`409 Conflict`	The request conflicts with the current state, such as a concurrent update.
`415 Unsupported Media Type`	The request body uses a media type the resource does not accept.
`500 Internal Server Error`	An unexpected server error occurred.
`503 Service Unavailable`	The server is temporarily unable to handle the request.

For 4xx and 5xx responses, the body describes the problem. For details, see Error handling.

Naming conventions

URLs, query parameters, and JSON properties all follow snake_case: they are lowercase, and words are separated by underscores. For example, a URL segment appears as shared_spaces, and a JSON property appears as creation_time.

Request size limit

The size of a POST or PUT request body is limited to approximately 100 MB. Requests that exceed the limit are rejected. If you need to send a large amount of data, split it across multiple requests.