Ketting is an attempt at making a generic Hypermedia API client for javascript. It uses a ‘link’ and following links as the most important primitive.

Last week I released version 2.5.0 on NPM so maybe it’s time to list some of the improvements since the last update in order from most to least interesting.

JSON:API support

JSON:API is a standard for making JSON-based APIs, and it has some support for hypermedia ideas as well.

In particular, the standard has a links object, and it also defines a relationship between collections and members of collections.

This release now ships with a ‘representor’ for JSON API, which means you can now do something like this:

const myResource = await home
  .follow('next') // This might be a HTML5 document
  .follow('author') // This might be a HAL document
  .follow('about') // This might be a JSON:API document

All of these will now be seamless regardless of which format any of these hops used, only when you get() and put() the format is relevant again.

A lot of help in getting this right came from JSON:API community members such as Gabe Sullice and Ethan Resnick. If you’re interested in the full discussion about how JSON:API maps to HATEOAS read the Github issue.

go() function

Not every endpoint will have every appropriate link to another resource. Sometimes you just have to work with what you have, and fetch a resource yourself.

The go() function is a function that exists on a resource and simply gives you a new resource based on the url you passed. The url can be relative and will be resolved based on the ‘current’ resource.

const anotherResource = resource.go('?q=hello');

Resource is generic

If you use typescript with this package, it might be desirable to have some typing.

Adding good support for this will be an ongoing process, but as a first step the Resource class is now generic.

This means that you can define a function such as:

function foo(): Resource<MyBodyType> {
  // ...
}

Typescript will then use MyBodyType as the type that will be returned from get() and refresh() and will demand that the value passed to put() has this type.

By default this is any.

I think this is a decent first step, but I also imagine this will have to continue to evolve.

esModuleInterop is false

The Typescript build now has esModuleInterop off. Apparently keeping it set to true caused anyone who uses the library and has this setting set to false to get errors.

So in order to not force people to change this setting, esModuleInterop is now off, which means the library will work regardless of your own preference.