About JSON Resource Servlet binding

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

The module provides a standalone HttpServlet implementation as part of its WAR artifact. The Servlet can be deployed and configured with a custom ConnectionFactory and HttpServletContextFactory. By default the Servlet will use an in memory back-end exposing a "/users" and a "/groups" end-point.

In addition, the module provides a JAR artifact which can be used for building more complex JSON Resource Servlets. As well as extending the HttpServlet implementation you can also use the HttpServletAdapter which adapts Servlet calls to JSON resource calls. An adapter can be used in any Servlet, just create a new instance and override the service() method in your Servlet to delegate all those calls to the adapter's service() method.

Get JSON Resource Servlet binding

JSON Resource Servlet 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.forgerock.commons</groupId>
        <artifactId>json-resource</artifactId>
        <version>2.5.0-SNAPSHOT</version>
    </dependency>
    <dependency>
        <groupId>org.forgerock.commons</groupId>
        <artifactId>json-resource-servlet</artifactId>
        <version>2.5.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 deploy the WAR and configure its web.xml configuration file as needed. By default it has the following key properties:

<servlet>
    <servlet-name>Users</servlet-name>
    <servlet-class>org.forgerock.json.resource.servlet.HttpServlet</servlet-class>

    <init-param>
        <param-name>connection-factory-class</param-name>
        <param-value>org.forgerock.json.resource.servlet.MemoryBackendConnectionFactoryProvider</param-value>
    </init-param>

    <init-param>
        <param-name>uri-template</param-name>
        <param-value></param-value>
    </init-param>
</servlet>

<servlet-mapping>
    <servlet-name>Users</servlet-name>
    <url-pattern>/users/*</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 Servlet 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, apart from the example Servlet configuration. 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 in the Servlet configuration using the servlet-mapping properties, or they 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

Content

N/A

Returns

The JSON representation of the resource that was read.

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 _filter parameter.

Method GET
Parameter

See common parameters

_queryId=ID

A string identifying a server side "stored" query. This parameter is mandatory if _filter 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 TBD (this feature is not yet fully implemented), but expected to be similar to the filter representation used in SCIM. 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.