ForgeRock CREST.js
Lightweight Library for Communicating With ForgeRock CREST APIs.
Prerequisites
ForgeRock CREST.js requires the fetch and Promise APIs to be available in the global environment.
Supported Versions
ForgeRock CREST.js supports CREST versions 2.0 and 2.1.
import { CRESTv2, CRESTv2_1 } from "@forgerock/crest-js";
Installation
via Yarn
yarn add @forgerock/crest-js
via NPM
npm install @forgerock/crest-js
Usage
Basic
import { CRESTv2 } from "@forgerock/crest-js";
const resource = new CRESTv2("http://www.domain.com/crest/api");
resource.get("id").then(json => {
// Success! `json` is an Object
}, error => {
if (error instanceof CRESTError) {
// CREST error
} else if (error instanceof RequestError) {
// Request could not be completed e.g. network failure
} else if (error instanceof ParseError) {
// Response couldn't be parsed as JSON
}
});
All the functions upon a CREST resource return Promises.
Promises allow for easily building on top of the core functionality, for example, with common handlers that deal with rejections consistently.
Supported Methods
import { CRESTv2_1 } from "@forgerock/crest-js";
const resource = new CRESTv2_1("http://www.domain.com/crest/api");
const body = { data: "value" };
// #action
resource.action("action");
resource.action("action", { body }); // Action with body
// #create
resource.create(body); // Server provided ID
resource.create(body, { id: "id" }); // Client provided ID
// #delete
resource.delete("id");
// #get
resource.get("id");
// #queryFilter
resource.queryFilter(); // Only supports `_queryFilter=true`
// #update
resource.update("id", body);
Pagination is currently only supported via the additional query strings option queryString.
See the API Documentation for all possible options.
Options
queryString
For adding additional query strings to the any request.
import { CRESTv2 } from "@forgerock/crest-js";
const resource = new CRESTv2("http://www.domain.com/crest/api");
resource.get("id", {
queryString: {
query: "value"
}
})
// => http://www.domain.com/crest/api/id?query=value
Query strings applied by ForgeRock CREST.js cannot be overridden.
import { CRESTv2 } from "@forgerock/crest-js";
const resource = new CRESTv2("http://www.domain.com/crest/api");
resource.action("action1", {
queryString: {
_action: "action2"
}
})
// => http://www.domain.com/crest/api?_action=action1
Middleware
One or many middleware can be applied to an CREST resource.
Each middleware is a function that takes a single Promise parameter, and returns a Promise to pass to the next middleware.
The first middleware in the chain is guaranteed to receive a Promise which is either resolved to a parsed JSON payload, or rejected with one of the defined error types.
import { CRESTv2_1 } from "@forgerock/crest-js";
const customMiddleware = (promise) => {
return promise.then((json) => {
// Success! `json` is an Object
const jsonToReturn = {
...json,
myAttribute: true
};
// Return value will be passed the next middleware
return json;
}, (error) => {
// Capture, rethrow or modify errors
throw new CustomError(error.message);
});
};
const resource = new CRESTv2_1("http://www.domain.com/crest/api", {
middleware: [customMiddleware]
});
Development
Project Structure
dist/ # Output of "yarn run build".
config/ # Tooling configuration files.
docs/ # API documentation And output of "yarn run docs".
src/ # Source code.
├── .babelrc # Babel configuration for source when executing "yarn run test" or "yarn run test:coverage".
└── ...
Building
Builds production CommonJS, ES and UMD versions into /dist.
yarn run build
Docs
Generates API JSDoc into /docs.
yarn run docs
Testing
Runs tests against the source.
yarn run test
The yarn command will pass arguments to the underlying command. For examples, use yarn run test --verbose --watch for continuous testing with extra output.
Test Coverage
Generates test coverage report.
yarn run test:coverage
Contributing
Contribute to ForgeRock CREST.js by opening a Pull Request.