Conventions


Authorization

To make a call to the Consent API, you can use basic authentication (username/password) or an OAuth 2.0 access token for API authentication. The access token is accepted per RFC 6750 through the Authorization HTTP request header. For more information about acquiring a bearer access token for your organization, see Getting started.

HTTP methods

The Consent API supports the following HTTP methods. Note that a resource may not support all listed methods below. When a method is not supported, the platform returns a 405 METHOD NOT ALLOWED error in the response.

  • POST

    Creates a new resource in the collection. If a specific resource is identified, it performs an operation on that resource.

  • PUT

    Creates a new (complete) resource in the collection. If a specific resource is identified, it updates all attribute values of the resource.

  • PATCH

    Updates the attributes on an object or a partial update for the specified attributes.

  • GET

    Lists or queries a collection of resources. If a specific resource is identified, it returns the attribute values for the specific resource.

  • DELETE

    Deletes or unlinks a resource from the collection.

A resource supports updating either by replacing the resource (PUT) or partially updating the resource (PATCH).

Replacing a resource

A PUT request is a replace operation. Requests submitted using PUT will replace attribute values specified in the request and clear any attribute values that aren’t specified.

A null value is represented in a resource by omitting the property, although you can specify null to explicitly clear the value.

Partial updates to a resource

A PATCH operation performs partial updates of a resource. The body of a PATCH operation is similar to that of a PUT operation. However, omitting an attribute in a PATCH operation results in the attribute being ignored.

You can use a value of null to explicitly clear the value.

Supported data exchange formats

The Consent API supports JSON as the data exchange format. The Content-type request header for the API call identifies the format of the request body for PUT, POST, and PATCH operations. The following sample identifies JSON as the data exchange type:

curl -X PATCH "https://<server>/consent/v1/consents/{consentRecordId}" \
-H "Content-type: application/json" \
-H "Authorization: Bearer jwtToken" \
-d "{
  "param1" : "value1",
  "param2" : "value2",
}"

Link expansion

You can optimize the information returned by a request through link expansion. Link expansion is helpful when you need the query to return detailed information from an additional resource in the response data. You can identify a resource to expand using the expand query string parameter in the request. The allowed values for the expand parameter are found in a resource’s _links field (not including “self”). The Consent API supports link expansion for the localizations resource only.

Here is a sample request that does not use the expand parameter.

GET /definitions/share-email

The response data looks like this:

{
  {
      "_links": {
          "localizations": [
              {
                  "href": "https://<server>/consent/v1/definitions/share-email/localizations/en-US",
                  "hreflang": "en-US"
              }
          ],
          "self": {
              "href": "https://<server>/consent/v1/definitions/share-email"
          }
      },
      "displayName": "Share Email!",
      "id": "share-email",
      "parameters": [
          "param1"
      ]
  }

When using the expand parameter in the request (GET /definitions/share-email?expand=localizations), the returned data for the share-email resource looks like this:

{
    "_embedded": {
        "localizations": [
            {
                "dataText": "Can we share your email address with our partners?",
                "id": "en-US",
                "locale": "en-US",
                "purposeText": "Receive email offers from our partners.",
                "version": "1.0"
            }
        ]
    },
    "_links": {
        "localizations": [
            {
                "href": "https://<server>/consent/v1/definitions/share-email/localizations/en-US",
                "hreflang": "en-US"
            }
        ],
        "self": {
            "href": "https://<server>/consent/v1/definitions/share-email"
        }
    },
    "displayName": "Share Email!",
    "id": "share-email",
    "parameters": [
        "param1"
    ]
}

Note: If available, you can specify multiple resources to expand in the query string by listing multiple attribute names separated by commas.

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.

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": "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 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. See [Link expansion](#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.

Filtering collections

Requests that are known to return a large number of items can be filtered using the filter query string parameter. The following SCIM protocol filtering operators are supported.

Operator Description Behavior
eq equal The attribute and operator values are not identical.
ne not equal The attribute and operator values must be identical for a match.
co contains The entire operator value must be a substring of the attribute value for a match.
sw starts with The entire operator value must be a substring of the attribute value, starting at the beginning of the attribute value. This criterion is satisfied if the two strings are identical.
ew ends with The entire operator value must be a substring of the attribute value, matching at the end of the attribute value. This criterion is satisfied if the two strings are identical.
pr present (has value) If the attribute has a non-empty or non-null value, or if it contains a non-empty node for complex attributes, there is a match.
gt greater than If the attribute value is greater than the operator value, there is a match. The actual comparison is dependent on the attribute type. For string attribute types, this is a lexicographical comparison, and for DateTime types, it is a chronological comparison. For integer attributes, it is a comparison by numeric value.
ge greater than or equal to If the attribute value is greater than or equal to the operator value, there is a match. The actual comparison is dependent on the attribute type. For string attribute types, this is a lexicographical comparison, and for DateTime types, it is a chronological comparison. For integer attributes, it is a comparison by numeric value.
lt less than If the attribute value is less than the operator value, there is a match. The actual comparison is dependent on the attribute type. For string attribute types, this is a lexicographical comparison, and for DateTime types, it is a chronological comparison. For integer attributes, it is a comparison by numeric value.
le less than or equal to If the attribute value is less than or equal to the operator value, there is a match. The actual comparison is dependent on the attribute type. For string attribute types, this is a lexicographical comparison, and for DateTime types, it is a chronological comparison. For integer attributes, it is a comparison by numeric value.

For example, here is a sample SCIM filtering expression that returns the localization resources where the locale starts with en and the data text contains the word email:

https://<server>/consent/v1/definitions/{id}}/localizations?filter=locale sw "en" and dataText co "email"

Here is the same filter with URL encoding to account for spaces (%20) and quotation marks (%22):

https://<server>/consent/v1/environments/{envID}/users?filter=locale%20sw%20%22en%22%20and%20dataText%20co%20%22email%22"

For more information about the SCIM Protocol Specification, see SCIM Filtering.