CREST API Descriptor

CREST is ForgeRock's standard library for exposing RESTful web services.

This document specifies an API descriptor that describes CREST APIs in a standard format that developers can read and tools can consume. API descriptors enable clients such as static documentation generators, live documentation websites, and other tooling.

When consuming a CREST API descriptor, the fundamental assumption is that the consumer knows CREST. Therefore, an API descriptor specifies which CRUDPAQ operations a resource supports, whether a resource supports MVCC, whether a create operation calls for a server-assigned or client-assigned ID, and what patch operations can be used with a resource that supports patch. An API descriptor does not describe CREST itself, however, nor does it describe how CREST binds to a transport protocol such as HTTP.

Status

This document is version 1.0.0.

Revision History

Conventions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

Types

In this document the following type names are used:

• frURI - A ForgeRock API Descriptor URI. These start with the frapi: scheme, and are followed by colon-separated heirarchical component IDs to make a unique identifier. For example: frapi:openam:identities, which could be used in a JSON Reference: frapi:openam:/:identities#/definitions/user

Specification

ApiDescription (Top-Level Object)

At the top level, the API is described as a collection of schema definitions, service definitions, errors, and paths (endpoints) available in the application.

The API documented by an ApiDescription is simply a set of CREST web services exposed to consumers. An ApiDescription MAY cover a single endpoint or an entire product. An ApiDescription does not necessarily represent a single, coherent library of services for a specific purpose.

The top-level MUST contain at least one of definitions, errors, paths, or services.

Properties

The top-level version and description properties apply to the entire API.

Individual request handlers MAY be versioned separately, as described in VersionedPath.

Definitions

Map of locally defined extended JSON schema, that can be referred to via JSON References.

Properties

Services

Map of locally defined service definitions, that can be referred to via JSON References.

A service definition describes resources and operations they support, independently of the path (endpoint) where the resource is exposed. Service definitions are useful when the path depends on configuration, and when multiple paths can expose the same web service.

Properties

Errors

Map of locally defined errors, that can be referred to via JSON References.

Properties

Reference

JSON Reference syntax referring to schemas, service definitions, and errors that are defined locally or externally.

Properties

Paths

Map of paths (endpoints) supported by the API being described.

Paths MAY include path parameters contained in curly braces, for example, /users/{userId}/devices/{deviceId}.

Paths MUST contain at least one VersionedPath.

Properties

VersionedPath

Optional version of the request handler at the top of a particular path.

When all request handlers share the same version defined at the top-level, API descriptors MAY omit this level of the Path hierarchy.

The resource MAY be specified using a Reference.

Properties

Only N and N.N formats are supported for a version number key.

The reserved value 0.0 means "unversioned". If 0.0 is used it MUST be the only VersionedPath entry for a path.

Resource

The resource accessible at a given path and also the CREST operations it supports.

Collection resources have items that are all of the same type. For example, each item in a collection of users is a user. In a collection that supports create, the items are the resources to create. In a collection that supports queries, the items are the items in the result array of the response resource.

Resources can have either items or subresources that support their own CREST operations, and that are versioned with the resource. For example, a subscriber has subscriptions. A resource cannot have both items and subresources - if a resource has an items then the subresources are declared on that node.

A resource MUST define at least one CRUDPAQ Operation.

Properties

Items

The resource type and operations support on the items of a collection.

An item MUST define at least one CRUDPA Operation.

Properties

SubResources

Sub-resources are resources that are a component part of their parent. As such, they share the version of the parent from the parent's path binding. If a sub-path is separately versioned from a parent path, it MUST be listed as a separate path in the Paths object, rather than as a sub-resource of the resource at the parent path.

Properties

Operation

A basic operation type for operations without any special features.

This is the supertype for all CRUDPAQ operations: All operations inherit these properties.

Properties

ApiError

Defines one of the possible error responses that are known to be returned by a given Operation. All standard CREST errors are defined under frapi:common, which is an API Descriptor that will always be available by default. Endpoints MAY overload any error code and unique description to define custom errors. CREST API clients should be prepared to handle undocumented/unexpected errors. It is a best practice to define a minimum ApiError array definition, with 500 Internal Server Error, as follows,

"errors" : [
    {"$ref" : "frapi:common#/errors/internalServerError"}
]

Properties

Parameter

Defines either an additional parameter for an operation that is not part of the request payload, or a path parameter expressed as a value surrounded by curly braces in a path.

Properties

Other appropriate fields as described in the JSON Schema Validation spec may also be used.

Create

Indicates that creating a new resource is supported.

Extends Operation.

Properties

Read

Indicates that reading the contents of an existing resource is supported.

Extends Operation.

Properties

No additional properties.

Update

Indicates that replacing the contents of an existing resource is supported.

Extends Operation.

Properties

No additional properties.

Delete

Indicates that deleting a resource is supported.

Extends Operation.

Properties

No additional properties.

Patch

Indicates that partially modifying the contents of an existing resource is supported.

Extends Operation.

Note that CREST has its own definition for the patch request payload. The content of the request payload is a JSON array whose elements are the modification operations to apply to the resource.

The following example adds the value admin to the roles field, and removes valueToBeRemoved from field/subfield:

[
  {
    "operation" : "add",
    "field" : "roles",
    "value" : "admin"
  },
  {
    "operation" : "remove",
    "field" : "field/subfield",
    "value" : "valueToBeRemoved"
  }
]

The request payload items' properties depend on the patch operation. The request payload values depend on the resource schema. Given these dependencies, a patch request payload has the following schema:

{
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "operation": {
        "type": "string",
        "enum": [
          "add",
          "remove",
          "replace",
          "increment",
          "move",
          "copy",
          "transform"
        ],
        "required": true
      },
      "field": {
        "type": "string"
      },
      "from": {
        "type": "string"
      },
      "value": {
        "type": "string"
      }
    }
  }
}

Properties

Action

Indicates that one or more additional action operations on the resource are supported.

Extends Operation.

Properties

Query

Indicates that searching or listing the resources in this resource container is supported.

Extends Operation.

Resource queries arrays can include up to one query filter operation, one query expression operation, and multiple queries by ID.

Properties

The following example shows a resource that supports all three types of query:

"paths": {
  "/openidm/managed/user": {
    "queries": [{
      "type": "EXPRESSION",
      "description": "Return the results of an SQL query such as `_queryExpression=select+%2A+from+managed_user`"
    }, {
      "type": "FILTER",
      "description": "Return resources matching the filter.",
      "queryableFields": ["*"]
    }, {
      "type": "ID",
      "queryId": "query-all-ids"
      "description": "Return all resources.",
    }]
  }
}

Schema

API descriptors use schemas to represent request payloads, response resources, and error responses.

API descriptors support using either a Reference to a defined schema, or OpenAPI-extended JSON schema with additional extensions for the following use cases:

Field Order

To specify the order of fields displayed in a UI.

Properties

Complex Read/Write States

To clarify read/write states more complex than readOnly.

Properties

Enumeration Value Descriptions

To assign titles/descriptions to enumeration values.

Enum titles are not supported officially for the JSON enum type.

This representation is already used in existing projects, and comes from JSON Editor.

Properties

Example

{
  "type": "string",
  "enum": ["value1","value2"],
  "options": {
    "enum_titles": ["title1","title2"]
  }
}

Example values

Similar to the OpenAPI specification, we support example values for JSON Schemas, but unlike OpenAPI, we also support these example values on sub properties too.

Properties

References

1. OpenAPI Specification, v2.0
2. JSON Reference, draft-03
3. JSON Schema: core definitions and terminology, draft-00
4. JSON Schema: interactive and non interactive validation, draft-00

Copyright 2016-2020 ForgeRock AS.