HTTP response headers

The Consent API includes information about the result of the operation in the HTTP headers. This enables you to determine the appropriate action to take without having to parse the response body.

The following HTTP Headers are returned by every operation:

HTTP response codes

The Consent API returns the status of an operation as a registered HTTP response code. The HTTP response codes are:

Operations may also return additional information about a failed operation in the HTTP response body.

For more information on HTTP response codes, see https://developer.mozilla.org/en-US/docs/Web/HTTP/Status

Synchronous responses

Responses for synchronous operations have the following behavior:

Response data structure

All Consent API resources return data using the HAL+JSON content type. The HAL media type provides a common format for linking API resources. HAL conventions adopted by the Consent APIs result in an easily readable structure for resource links and for expressing embedded resources contained within parent resources. The following sample shows how embedded resources are structured in the response data.

{
    "count": 3,
    "size": 3,
    "_links": {
        "self": {
            "href": "https://<server>/consent/v1/definitions"
        }
    },
    "_embedded": {
        "definitions": [
            {
                "id": "1813bc13-8d13-4e88-a825-d40bfe82777b",
                "name": "Defn 1 name",
                "description": "Defn1 description",
              }
          ...
    }
}

For collections, the result data returns a count and size attribute, and all API requests return a self URL under the _links attribute that identifies the URI of the main resource.

The _embedded attribute lists all the results in the collection. In the sample above, the count attributes tells you that there are three definitions in the collection.

Relationships, links, and references

Relationships between resources or operations can be described as follows:

These relationships and references are represented as follows:

Errors

Errors generated by the Consent API are intended to allow you to resolve specific errors programmatically. An error response consists of a high-level error code that must be handled by the client and optional details containing specific information on how to resolve the fault. The Consent API errors return a response payload formatted as follows:

{
    "id": "454",
    "code": "INVALID_DATA",
    "message": "Unable to parse request: Can not construct instance of com.unboundid.directory.server.extensions.consent.types.ConsentStatus from String value (\"foo\"): value not one of declared Enum instance names: [restricted, revoked, pending, denied, accepted] at line: -1, column: -1"
}
Attribute Required Description
id Yes A unique identifier that is stored in log files and always included in an error response. This value can be used to track the error received by the client (with server-side activity included for troubleshooting purposes).
code Yes A general fault code which the client must handle to provide all exception handling routines and to localize messages for users. This code is common across all services and is human readable (such as a defined constant rather than a number).
message Yes A short description of the error. This message is intended to assist with debugging and is returned in English only.