Introduction

The Dynamic Content API is a HTTP-based API that applies REST principles. In this guide you will find:

  • Descriptions of request and response formats

  • Details of error codes

  • Guidance on how to best integrate with that Dynamic Content API

Routing

Resources can usually be retrieved using a /resource-types/:id endpoint. Collection resources will always be pluralised, regardless of how they are accessed. In cases where resources are nested under a parent resource, and this context is necessary for the request, this information is included in the routing. For example, while a Content Repository can be retrieved by id using GET /content-repositories/:id, to create a new Content Repository it is necessary to supply the ID of the parent Hub, so the route would take the form POST /hubs/:hubId/content-repositories.

HAL

Resources are returned in the HAL format, which provides a representation of HATEOAS information in JSON. This allows for discoverability of endpoints from responses, as a response for a resource will contain links to related resources and actions. Links are contained within a _links object, and are keyed by name. In some cases, such as resource listing or search results, linked resources are included in the response inside an _embedded object, allowing multiple resource to be returned within the same response body.

Status Codes

Response codes for the API are described in the table below.

when making decisions on error conditions, integrate against the class of error (4xx vs 5xx) rather than specific error codes (403 vs 404 vs 409) as error codes are more likely to change in subsequent API releases.

Status Code Table

Status Code Reason Phrase Purpose

200

OK

Successful retrieval or update of a resource or list of resources

201

Created

Successful creation of a resource

202

Accepted

A background task has been initiated, but is still processing

204

No Content

Indicates the following:
* Success with deleting a resource
* Success with granting or revoking permissions
* Success with nothing to report

400

Bad Request

Non-specific error with request

401

Unauthorised

No valid token was supplied in the request, or the token could not be decoded

403

Forbidden

The user lacks either the required functional or ACL permissions to make this request

404

Not Found

The requested resource does not exist, or the user does not have access to it

405

Method Not Allowed

The requested HTTP method is not permitted for this resource type

406

Not Acceptable

The requested resource is not available in the format requested by the user agent

409

Conflict

The requested change conflicts with the current state of the resource

415

Unsupported Media Type

The format of the resource supplied by the user agent is not supported by the server

500

Internal Server Error

Non specific error occurred on the server

Error Response Format

If an error occurs, the response body contains a JSON object containing an errors array. This will contain one or more error objects, containing a message field describing the error, and context specific metadata relating to this instance of the error.

HTTP/1.1 409 Conflict
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 145

{
  "errors" : [ {
    "entity" : "Hub",
    "property" : "name",
    "invalidValue" : "anya-finn",
    "message" : "name must be unique"
  } ]
}

Guidance on using HTTP PATCH

When updating a resource, the PATCH method is used. When making a PATCH request, any fields specified in the request will overwrite their associated values in the stored resource, but omitted fields will remain unchanged. This is in contrast to the PUT method, which would set omitted fields to null, and is not supported in this API. When making a PATCH request to a resource containing nested JSON objects, it is important to note that child objects are replaced completely, and do not inherit the PATCH functionality of the root object.

For example, given a stored resource in the format:

{
  "foo": {
    "bar": "abc",
    "baz": "xyz"
  },
  "bar": "123"
}

When the following request body is used in a PATCH request:

{
  "foo": {
    "bar": "def"
  }
}

The resource would be transformed to the following:

{
  "foo": {
    "bar": "def"
  },
  "bar": "123"
}

Payload Considerations

When submitting a JSON payload to the API, the first complete JSON object in the body will be accepted, and any additional information will be discarded. For example:

{
  "foo": {
    "bar": "def"
  }},
  "this": "will be ignored"
}

In the above example, there is an extra closing brace and additional characters that follow a valid JSON object. Any extra input characters like this will be ignored by the API.