dunglas / ketting

Ketting is a Hypermedia client for javascript

Ketting 🔗 - A hypermedia client for javascript

• Go to the Wiki for full documentation.

Introduction

The Ketting library is a generic REST client with Hypermedia features.

The library will work with any JSON-based HTTP API, but it gets superpowers when using it with formats that have support for links, including:

• HAL
• JSON:API
• Siren,
• Collection+JSON

And it even works with HTML links, and HTTP Link Headers.

Ketting is designed to both work in the browser and in Node.js. Additionally, it has [react bindings][ketting-react] that will make it work in a way that's familiar to Apollo-Client users.

Example

const ketting = new Ketting('https://api.example.org/');

// Follow a link with rel="author". This could be a HTML5 `<link>`, a
// HAL `_links` or a HTTP `Link:`.
const author = await ketting.follow('author');

// Grab the current state
const authorState = await author.get();

// Change the firstName property of the object. Note that this assumes JSON.
authorState.data.firstName = 'Evert';

// Save the new state
await author.put(authorState);

Docs

• Installation
• Full documentation
• Authentication

Notable Features

Ketting is a library that sits on top of Fetch API to provide a RESTful interface and make it easier to follow REST best practices more strictly.

It provides some useful abstractions that make it easier to work with true hypermedia / HATEOAS servers. It currently parses many hypermedia formats and has a deep understanding of links and embedded resources. There's also support for parsing and following links from HTML documents, and it understands the HTTP Link: header.

It also has support for 'fetch middlewares', which is used to implement OAuth2 support, but also opens the door to development of other plugins.

Using this library it becomes very easy to follow links from a single bookmark, and discover resources and features on the server.

Supported formats:

• HAL
• Siren - Including support for actions.
• HTML - Can automatically follow <link> and <a> element with rel= attributes, and submit HTML <form>s.
• HTTP Link header - automatically registers as links regardless of format.
• JSON:API - Understands the links object and registers collection members as item relationships.
• application/problem+json - Will extract useful information from the standard problem object and embed them in exception objects.

Other features:

• Prefer-Push
• Prefer-Transclude
• It can submit HTML forms and Siren actions.

Read further on the Wiki