cameron-martin / crest-js

Lightweight Library for Communicating With ForgeRock CREST APIs.

ForgeRock CREST.js

Lightweight Library for Communicating With ForgeRock CREST APIs.

• Prerequisites
• Supported Versions
• Installation
  • via Yarn
  • via NPM
• Usage
  • Basic
  • Supported Methods
  • Options
    • queryString
  • Middleware
• Development
  • Project Structure
  • Building
  • Docs
  • Testing
  • Test Coverage
• Contributing
• Further Reading

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.

Further Reading

• About ForgeRock Common REST
• Specification of the CREST HTTP protocol