About JSON Resource core library

JSON Resource provides a common framework for implementing RESTful APIs within ForgeRock projects. It is split into two parts:

  • json-resource - this Maven module which provides the core interfaces and types such as Connections , Requests , and RequestHandlers
  • json-resource-servlet - a Maven module which provides J2EE6 Servlet integration and defines a common HTTP based REST API for interacting with JSON Resources.

Get JSON Resource core library

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

<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>
</dependencies>

See the documentation for json-resource-servlet for instructions on building your own JSON Resource based HTTP Servlets.

Getting started

The following example shows how JSON Resource may be used to create a simple in-memory back-end, connect to it using an internal connection, add two user resources, and then query them:

// Create a new in memory backend which will store user resources.
InMemoryBackend users = new InMemoryBackend();

// Create a router request handler and route requests for user
// resources to the in memory backend.
Router router = new Router();
router.addRoute(EQUALS, "users", users);

// Obtain an internal connection to the router.
Connection connection = newInternalConnection(router);

// Create two users.
JsonValue alice = new JsonValue(new LinkedHashMap<String, Object>());
alice.put("name", "Alice");
alice.put("age", 21);
alice.put("role", "administrator");
Resource r1 = connection.create(new RootContext(), newCreateRequest("users", alice));

JsonValue bob = new JsonValue(new LinkedHashMap<String, Object>());
bob.put("name", "Bob");
bob.put("age", 40);
bob.put("role", "sales");
Resource r2 = connection.create(new RootContext(), newCreateRequest("users", bob));

// Read a single user.
Resource r3 = connection.read(new RootContext(), newReadRequest("users", r1.getId()));
assertEquals(r1, r3);

// Update a single user.
bob.put("role", "marketing");
Resource r4 = connection.update(new RootContext(), newUpdateRequest("users", r2.getId(),
        bob));

// Retrieve the list of users.
Set<Resource> results = new HashSet<Resource>();
connection.query(new RootContext(), newQueryRequest("users"), results);
assertEquals(results, new HashSet<Resource>(Arrays.asList(r3, r4)));

Known Issues

At the moment, JSON Resource is mostly complete and the existing APIs can be considered as stable (no changes are envisaged at the moment). However, there are a few notable missing features which are being tracked in our issue tracker .