Ketting 1.0 release.
So this evening I released 1.0, and also share some information about it here. It’s been almost a year since I blogged! Really gotta get back on this horse.
A bit of background
Nearly 2 years ago we implemented a new API at a company I worked at. We chose to go the REST/hypermedia/HATEOAS route and use HAL as the primary format.
I had a drive to try and see what a good client for this would look like, so I decided to write my own in my free time.
This client is written in Javacript, works in node.js and in browsers. We use it as a real client, but also doing black-box testing of API’s.
A summarized list of features
- It parses HAL
_linksand provides a convenient API for following links.
- Uses the Fetch API for HTTP requests and is heavily promise-based.
- Automatically parsed items in
_embeddedand stores them in a cache. The nice thing about this is that if a server chooses to embed certain items, the client will automatically adapt and ‘upgrade’ to take advantage of this, resulting in less requests.
application/problem+jsonresponses and automatically converts them to exceptions.
- Supports Basic auth, Bearer tokens.
- Also implements some of OAuth2, including the
client_credentialsgrant types and will automatically refresh expired access tokens if a refresh token was provided.
- Supports HTTP
Link:headers and merges them in with HAL links, allowing you to follow links on non-HAL or non-JSON resources.
- Similarly, if given a html document it will extract all
How does it work?
Generally with REST you’ll want to ‘discover’ urls based on link relationships, and not hardcode them. This is the main focus of the API.
The following sample does the following:
- Create a new client and specify the ‘bookmark url’ of the API to
- Find a collection of articles using
- Grab the first article in that collection (generally items in a collection
rel="item". See RFC6573).
- Do a
GETrequest on the article, and afterwards follow the
- Lastly, change the name of the author by doing a
const ketting = new Ketting('https://api.example.org');
// Ketting uses a special promise that has a `follow` function so it can be // chained to do multiple hops. const articleResource = await ketting.follow('articleCollection').follow('item'); const articleBody = await article.get();
const authorResource = await articleResource.follow(
Truncated by Planet PHP, read more at the original (another 2097 bytes)