PingDirectory API Reference

Consent API Responses

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:

  • Access-Control-Allow-Headers

    This header is used in response to a preflight request to indicate that HTTP headers can be used when making a request.

  • Access-Control-Allow-Max-Age

    This header specifies how long the results of a preflight request can be cached.

  • Access-Control-Allow-Methods

    This header specifies specifies the method or methods allowed when accessing the resource in response to a preflight request.

  • Content-Type

    This header specifies the data exchange format for the result data. This value should be application/HAL+json.

  • Date

    This header specifies the date the response was sent.

HTTP response codes

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

  • 200-299

    Confirms a successful call.

  • 300-399

    Indicates that the call or subsequent calls should be made to another resource.

  • 400-499

    Shows that an exception occurred, generally due to client code, insufficient permissions, or incorrect parameters.

  • 500-599

    Shows that an error occurred, generally due to an issue with the service (for example, a service outage).

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

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

Synchronous responses

Responses for synchronous operations have the following behavior:

  • GET operations

    A request that returns a body also returns the code 200 OK with the resource in the body of the response.

  • POST operations

    A request that creates a new resource returns 201 CREATED with a Location header containing the location of the created resource.

  • PUT or PATCH operations

    A request that updates a resource returns 200 OK and the full resource in the body.

  • DELETE operations

    A request that deletes a resource returns 204 NO CONTENT.

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": "5caa81af-ec05-41ff-a709-c7378007a99c",
                "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 between resources or operations can be described as follows:

  • self link.

    All resources return a self link in the response body.

  • localizations link

    Definition resources include a localizations link object that contains zero or more child localization resources. Consent resources (consent records) include a single localizations link object.

  • parent link.

    Localization resources include a parent link object that contains a single parent definition resource.

  • definitions

    Consent resources (consent records) include a definitions link object that contains a single definition resource.

These relationships and references are represented as follows:

  • Links are represented using JSON HAL conventions (such as, in a _links object).

  • Links are represented as absolute URLs.

  • Links can be expanded using the expand parameter. Refer to Link expansion. The links can also be referenced via the "property-as-resource" pattern.

  • References as attributes have an id value and may also have additional attributes (such as displayName).

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.