Child pages
  • Defining API Descriptors

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Updated link to CREST API Descriptor Specification

...

This wiki page contains resources and tips & tricks related to defining API Descriptors.

CREST API Descriptor Specification

Examples

ClassNotes
org.forgerock.openidm.external.email.impl.EmailServiceImpl
  • API Descriptor annotations
  • JSON Schema from flat files
  • Single "action"
org.forgerock.openidm.idp.impl.IdentityProviderService
  • API Descriptor annotations
  • JSON Schema from annotated POJO classes
  • Multiple "actions"
  • Resource schema and "read" endpoint
org.forgerock.openidm.managed.ManagedObjectService
  • API Descriptor from Describable interface
  • JSON Schema read from managed.json
Example in forgerock-commons

Annotations

Two sets of annotations can often be used to describe portions of an API Descriptor. There are a set of CREST related annotations, that define the actual API endpoints, and another set of annotations that extend Jackson support for JSON Schema v4 generation.

CREST API Descriptor annotations

Java AnnotationNotes
SingletonProvider
 

CollectionProvider
 

RequestHandler

In OpenIDM, use,

final Router router = new DescribableRouter();

for the parent class that adds RequestHandler instances onto the router.

Handler
 

Path
 

Operation
 

ApiError

Defines error responses that the user of the API needs to be aware of.

Example

Points to a JSON example text-file. This is not JSON Schema, but an actual example of the resource / payload.

Parameter

Defines a parameter either as URL path-template (ParameterSource.PATH) or as a query-parameter (ParameterSource.ADDITIONAL).

Schema

Points to a JSON Schema v4 text-file or POJO class (see annotations below).
Create
 

Read
 

Update
 

Delete
 

Patch
 

Query
 

Action / Actions

Actions are unique, because custom request / response payload schemas can be defined, whereas the other CRUDPAQ operations are assumed to use one resource-schema for the endpoint.

Use the "Actions" annotation when an endpoint supports multiple actions.

 


Annotations that generate JSON Schema,

...

Please also refer to the Jackson Annotations documentation (examples), which are often necessary when field names need to be renamed or hidden/ignored, for example.

JSON Schema FieldJava AnnotationNotes
typeprovided by JacksonJackson determines the correct JSON type for the POJO class and nested fields.
propertiesprovided by JacksonFields on an object correspond to getter/setters on your POJO.
enumprovided by JacksonA Java "enum" will be converted into a JSON Schema "enum".
options/enum_titleorg.forgerock.api.annotations.EnumTitleProvide titles for enum items.
descriptionorg.forgerock.api.annotations.DescriptionDescription of class or field.
titleorg.forgerock.api.annotations.TitleShort title for class or field.
itemsprovided by Jackson

A List<String> or String[] field on the POJO will define itself as a JSON Schema "type":"array" and the "items" will have "type":"string".

Warning: might be restricted to one array-item type (not multiple)

uniqueItemsorg.forgerock.api.annotations.UniqueItems"uniqueItems":true means that all array/collection items must be unique
readPolicyorg.forgerock.api.annotations.PropertyPolicies
 

returnOnDemandorg.forgerock.api.annotations.PropertyPoliciesWhether or not a field is always returned or if it must be requested via "_fields".
writePolicyorg.forgerock.api.annotations.PropertyPolicies
 

errorOnWritePolicyFailureorg.forgerock.api.annotations.PropertyPolicies
 

propertyOrderorg.forgerock.api.annotations.PropertyOrderJackson normally orders properties (fields) in the order they are defined in the POJO class, so this annotation makes the ordering more specific if that is necessary.
minLengthjavax.validation.constraints.SizeMinimum string length. Can be used to allow "empty string".
maxLengthjavax.validation.constraints.SizeMaximum string length.
minItemsjavax.validation.constraints.SizeMinimum items in an array/set.
maxItemsjavax.validation.constraints.SizeMaximum items in an array/set.
minimum (for int/long)javax.validation.constraints.MinMinimum value (inclusive) for an int/long.
maximum (for int/long)javax.validation.constraints.MaxMaximum value (inclusive) for an int/long.
minimum (for any? number)javax.validation.constraints.DecimalMinMinimum value (inclusive) for any Java number.
maximum (for any? number)javax.validation.constraints.DecimalMaxMaximum value (inclusive) for any Java number.
exclusiveMinimumjavax.validation.constraints.DecimalMinMinimum value (exclusive) for any Java number.
multipleOforg.forgerock.api.annotations.MultipleOf"multipleOf":2.0 means that the number is a multiple of 2 (e.g., 2, 4, 6...)
exclusiveMaximumjavax.validation.constraints.DecimalMinMaximum value (exclusive) for any Java number.
requiredjavax.validation.constraints.NotNullSpecify field as "non-null", which translates to "required":true in JSON Schema.
readOnlyorg.forgerock.api.annotations.ReadOnlyField is read-only.
patternjavax.validation.constraints.PatternRegex that a "string" field should match.
formatorg.forgerock.api.annotations.Format

Supported "format" values by JSON type,

  • integer
    • int32 (default)
    • int64
  • number
    • double (default)
    • float
    • int32
    • int64
  • string
    • byte (base64)
    • binary (base64)
    • full-date (RFC 3339)
    • date-time (RFC 3339)
    • password
    • uuid
defaultorg.forgerock.api.annotations.Default

The "default" value, represented as a string.

NOTE: all JSON types are supported when defining a "default" field using a JSON Schema text-file (non-annotation)

additionalPropertiesorg.forgerock.api.annotations.AdditionalPropertiesUseful when the JSON object is a "map" of "string" keys and values of the given type, but the keys might be only known at runtime.

JSON Schema Text Files

JSON Schema's for API Descriptor resources and request / response payloads can be defined in text files, using JSON Schema v4 syntax. For most common use-cases annotations on a POJO can generate the appropriate schema, but there are times when the annotations fall short. For example, the @Default annotation currently only supports string representations of simple default-values (e.g., "text", "1.0", "true"), so if you want to define a default  JSON object or array value, you will need to use a raw JSON Schema text-file.