About Wren Security Commons REST - JSON Resource HTTP Binding

JSON Resource HTTP provides HTTP integration and defines a common HTTP based REST API for interacting with JSON Resources.

See the JSON Resource Examples project json-resource-examples for an example standalone WAR artifact which demonstrates the integration of JSON Resource with the Common HTTP Framework.

The module provides a JAR artifact which can be used for building complex JSON Resource HTTP applications.

Get Wren Security Commons REST - JSON Resource HTTP Binding

JSON Resource HTTP is built and made available using Maven. Your project can use JSON Resource by declaring the following Maven dependencies:

<repositories>
    <repository>
        <id>forgerock-staging-repository</id>
        <name>ForgeRock Release Repository</name>
        <url>http://maven.forgerock.org/repo/releases</url>
        <snapshots>
            <enabled>false</enabled>
        </snapshots>
    </repository>
    <repository>
        <id>forgerock-snapshots-repository</id>
        <name>ForgeRock Snapshot Repository</name>
        <url>http://maven.forgerock.org/repo/snapshots</url>
        <releases>
            <enabled>false</enabled>
        </releases>
    </repository>
</repositories>

...

<dependencies>
    <dependency>
        <groupId>org.wrensecurity.commons</groupId>
        <artifactId>json-resource</artifactId>
        <version>23.0.0-SNAPSHOT</version>
    </dependency>
    <dependency>
        <groupId>org.wrensecurity.commons</groupId>
        <artifactId>json-resource-http</artifactId>
        <version>23.0.0-SNAPSHOT</version>
    </dependency>
</dependencies>

See the documentation for json-resource for instructions on building your own JSON Resources.

Getting started

The simplest way to get started is to checkout the json-resource-examples module and to deploy the WAR and configure its web.xml configuration file as needed. By default it has the following key properties:

<servlet>
    <servlet-name>CREST HTTP Application</servlet-name>
    <servlet-class>org.forgerock.json.resource.http.examples.CrestHttpApplication</servlet-class>
</servlet>

<servlet-mapping>
    <servlet-name>HTTP Application</servlet-name>
    <url-pattern>/*</url-pattern>
</servlet-mapping>

You can even check out the source code for this Maven module and run the default Servlet directly as follows:

mvn jetty:run

Overview of the REST API

JSON Resource HTTP is a library and as such provides a common framework for developing ForgeRock REST APIs. It does not expose any end-points itself, e.g. users. More specifically, this library defines the types of operations and their parameters, but it is left to the application to define the following:

The end-points - top-level end-points may be defined using a Router.
The schema used for resources passed to and from the JSON Resources. At some point we do expect to define a common schema for common types of resource, such as users and groups.
The set of extended "actions" which may be performed against a resource. Only the core operations of "create", "delete", "patch", "query", "read", and "update" are specified.

The following sub-sections describe each of the core operations in more detail:

Creating resources using POST

A POST create request should be used when the resource to be created will have a server provided resource ID (e.g. a UUID). It may also be used in cases where the resource ID is client provided, but only as long as the resource ID is included as a field within the new resource.

POST create requests should target the resource container and must include the parameter _action=create.

Method	`POST`
Parameter	See common parameters
`_action=create`	Mandatory parameter which must be equal to the value "create" indicating that this is a request to create a new resource.
Content	The JSON representation of the resource to be created.
Returns	The JSON representation of the resource that was created.

Example:

POST /users?_action=create  HTTP/1.1
Host: example.com
Accept: application/json
Content-Type: application/json
Content-Length: ...
{
  "uid" : "alice",
  "email" : "alice@example.com"
}

Creating resources using PUT

A PUT create request should be used when the resource to be created has a known resource ID. The resource ID is specified as part of the target resource name, and may also be included as a field within the new resource, in which case the two must be equivalent.

PUT create requests should target the new resource and include the HTTP header If-None-Match: *.

Method	`PUT`
Parameter	See common parameters
Content	The JSON representation of the resource to be created.
Returns	The JSON representation of the resource that was created.

Example:

PUT /users/1  HTTP/1.1
Host: example.com
Accept: application/json
Content-Type: application/json
Content-Length: ...
If-None-Match: *
{
  "uid" : "alice",
  "email" : "alice@example.com"
}

Reading resources

To read an existing resource send a GET request targeting the resource to be read.

Method	`GET`
Parameter	See common parameters
`_mimeType=mimeType`	A string that identifies the media type for the response content. When this parameter is used only 1 field value may be returned using the `_fields` parameter.
Content	N/A
Returns	The JSON representation of the resource that was read if the `_mimeType` parameter is not used. Otherwise the requested resource field is returned with the content type specified in the `_mimeType` parameter

Example:

GET /users/1  HTTP/1.1
Host: example.com
Accept: application/json

Querying/listing resources

To search or list the resources contained within a resource container send a GET request targeting the resource container and including either a _queryId or _queryFilter parameter.

Method	`GET`
Parameter	See common parameters
`_queryId=ID`	A string identifying a server side "stored" query. This parameter is mandatory if `_queryFilter` is not specified.
`_queryFilter=FILTER`	A filter expression which will be used to determine whether or not a resource should be included in the returned results. The filter format is described in the Javadoc for the `QueryFilter` class. This parameter is mandatory if `_queryId` is not specified.
`_sortKeys=[+-]FIELD,...`	Optional parameter containing a comma separated list of field references specifying which fields of the targeted JSON resources should be used as sort keys. A sort key is a JSON pointer optionally prefixed with a "+" or "-" character indicating whether the key is to be sorted in ascending or descending order. Default is to not sort results.
`_pagedResultsCookie=STRING`	Optional opaque cookie which is used by the server to track its position in the set of query results. Paged results will be enabled if and only if the `_pageSize` is non-zero. The cookie must be not be specified in the initial query request. Subsequent query requests must include the cookie returned with the previous query result `pagedResultsCookie` field, until the server returns a `null` cookie indicating that the final page of results has been returned. Default behavior is to not return paged query results.
`_pagedResultsOffset=INTEGER`	Optional parameter specifying the index within the result set of the first result which should be returned. Paged results will be enabled if and only if the page size is non-zero. If the parameter is not present or a value less than 1 is specified then the page following the last page returned will be returned. A value equal to or greater than 1 indicates that a specific page should be returned starting from the position specified. Default behavior is to return the page following the previous returned page.
`_pageSize=INTEGER`	Optional parameter indicating that query results are returned in pages of the specified size. For all paged result requests other than the initial request, a cookie should be provided with the query request. Default behavior is to not return paged query results.
`arg1=value1&arg2=value2&...&argn=valuen`	Additional parameters supported by the stored query. By convention argument names should not begin with an underscore. It is an error to include additional parameters if a `_filter` is specified.
Content	N/A
Returns	A JSON object containing the following three fields: results - an array containing the matching resources, or next page of matching resources if paged results have been requested. pagedResultsCookie - the opaque cookie which should be included with the next paged results query if paged results have been requested, otherwise `null`. remainingPagedResults - an estimate of the number of remaining paged results, or `-1` if the number is not known, or if paged results have not been requested.

Example:

GET /users?_queryId=all  HTTP/1.1
Host: example.com
Accept: application/json

Updating resources

To replace the contents of an existing resource send a PUT request targeting the new resource and optionally include the HTTP header "If-Match" specifying the version if MVCC is needed.

Method	`PUT`
Parameter	See common parameters
Content	The JSON representation of the resource to be updated.
Returns	The JSON representation of the resource that was updated.

Example:

PUT /users/1  HTTP/1.1
Host: example.com
Accept: application/json
Content-Type: application/json
Content-Length: ...
If-Match: "1"
{
  "uid" : "alice",
  "email" : "alice@example.com"
}

Patching resources

Patch operations are not yet supported.

Deleting resources

To delete an existing resource send a DELETE request targeting the resource to be deleted and optionally include the HTTP header "If-Match" specifying the version if MVCC is needed.

Method	`DELETE`
Parameter	See common parameters
Content	N/A
Returns	The JSON representation of the resource that was deleted.

Example:

DELETE /users/1  HTTP/1.1
Host: example.com
Accept: application/json
If-Match: "1"

Performing extended actions against resources

Some resources may support additional operations which can performed against them. These operations are performed by sending a POST request specifying the type of action to be performed using the _action parameter. The request may include zero or more implementation specific parameters.

Note that the action identifier "create" is reserved exclusively for resource creation.

Method	`POST`
Parameter	See common parameters
`_action=ID`	Mandatory parameter which identifying the type of action to be performed against the resource.
`arg1=value1&arg2=value2&...&argn=valuen`	Additional parameters supported by the action. By convention argument names should not begin with an underscore.
Content	The action specified JSON request content if applicable.
Returns	The action specified JSON response content if applicable.

Example:

POST /tasks/1?_action=cancel  HTTP/1.1
Host: example.com
Accept: application/json

Common request parameters

The following table lists the common HTTP request parameters which may be used with any type of request.

Parameter	Description
`_fields=FIELD,...`	Optional parameter containing a comma separated list of field references specifying which fields of the targeted JSON resource should be returned. Default is to return all fields.
`_prettyPrint=true\|false`	Optional parameter requesting that the returned JSON resource content should be formatted to be more human readable. Default is false.

Known Issues

See the documentation for json-resource for a list of known issues.