We just released version 7 of Ketting. Ketting is a generic HATEOAS client for Javascript.
A whole bunch of features have been added since September. We've been testing Ketting 7 in beta since January, so I'm excited to get this out the door.
I've been working on this project since 2016. Normally, I would expect a project like this to get a little stale. For me personally, the opposite has been true and using Ketting (especially with React) is starting to feel a bit like a paradigm shift.
Read on to see what's new!
What is Ketting?
In short: Ketting is a generic REST client for Javascript. You can use it for pushing JSON objects via HTTP, but the richer your API is in terms of best practices and standard formats, the more it can automatically do for you.
It has support for Hypermedia formats such as HAL, Siren, Collection+JSON, JSON:API and can even understand and follow links from HTML.
In the past it was not uncommon to hear that HATEOAS is lacking a good generic client. If you are a Javascript/Typescript user this is no longer true.
More information can be found on the Github page.
What's new?
Better HAL-Forms support
HAL-Forms is an extension of HAL, and adds support for 'actions' or 'forms', similar to what the <form>
tag is to HTML.
Since the start of the year HAL-Forms has seen major updates, which was a collaborative effort by several people from projects in the HAL community (including Spring HATEOAS and yours truly) and lead by it's author Mike Amudsen.
Spring HATEOAS released its HAL-Forms updates in version 1.3 M2 (unclear if this is a stable release or not), and Ketting follows today.
Major new features in HAL-Forms include:
- Support for lookups
- Example use-case is rendering dropdowns/comboboxes.
- The list of possible options can either be provided in-line or via an external resource.
- JSON and
text/csv
is support for external resources.
- Support for most of the HTML5 input types, such as
checkbox
,color
,tel
,email
,textarea
, etc. - Support for many of the field attributes that also exist in HTML5 form fields, such as
placeholder
,min
,max
,step
,cols
,rows
, and others. - Support for a form
target
. Previously this could also be supplied via the URI. - Support for multiple forms per document.
React bindings: <RequireLogin>
(note: all of the new react-ketting features were backported to Ketting 6)
react-ketting now has a RequireLogin
component, that can be use to handle the OAuth2 authorization_code
flow in React applications.
Example usage:
function MyApp() {
return <RequireLogin
clientId="my-oauth2-client-id"
authorizeEndpoint="https://..."
tokenEndpoint="https://..">
You are now logged in!
</RequireLogin>;
}
React-bindings: useCollection
A useCollection
hook was added to easily render a collection on a server.
Example usage:
import { useCollection, useResource } from 'react-ketting';
import { Resource } from 'resource';
type Article = {
title: string;
body: string;
}
function ArticleList() {
const { loading, items } = useCollection<Article>('/articles');
if (loading) return <div>Loading...</div>;
return <section>
<h1>Articles!</h1>
{items.map( item => <ArticleItem key={item.uri} resource={item} /> ) }
</section>;
}
function ArticleItem({resource}: { resource: Resource<Article> }) {
const { loading, data } = useResource(resource);
if (loading) return <div>Loading...</div>;
return <div>
<h2>{data.title}</h2>
<p>{data.body}
</div>
}
React-bindings: refreshOnStale
Both useResource
and useCollection
got a refreshOnStale
flag, that will cause Ketting to automatically ask the server for a new resource state if the cache is marked stale for a resource.
This can have a pretty magical effect when you (for example) use a POST
request on a collection to add a new member.
If you also used a useCollection
hook on the same page to show the collection, that collection will automatically refresh it's own list.
The first fetch of useCollection
will include a Prefer-Transclude
HTTP header, telling the user to (ideally) embed every item of the collection in the response, but subsequent refreshes will not.
This means the first time we only need 1 HTTP request, but for refreshes only the collection itself (and not it's members) need to be returned.
If your 'create' operation also returned Content-Location
, you can remove one more HTTP request from that list.
Similarly this can be used for DELETE
requests of members of the collection, as long as your response includes Link: </parent-collection>; rel="invalidates"
, the collection will also automatically re-render with the deleted item removed.
For one application we took this a step further, and used Websockets to emit 'stale' events from the server. With virtually no modifications to the frontend, we were able to turn a single-user web application into an application that
could reflect changes in real-time from other users who were using the application at the same time. This really felt like an emerging property of a well designed system (standing on the shoulders of decades of Hypermedia, HTTP and REST research).
Personally I'm very hyped about this feature, and I can't wait to demo this on a meetups or a conferences (if my talk proposals ever get accepted!?).
Deprecation warnings
Ketting 7 will now emit warnings when it encounters a Deprecation
or Sunset
header, or when a link contains the status: "deprecated"
hint.
For more information about this feature, read my previous article about this feature.
Removed support for Prefer-Push
HTTP/2 Push support in browsers is effectively dead. To reduce drag, I've removed the Prefer-Push
feature from Ketting.
Smarter caching of newly created resoures.
If you use Ketting to create a new resource (for example with POST
), and the server returns a Content-Location
header in its response, it will store the response body with the new URI in it's cache.
This can potentially reduce roundtrips. Content-Location
is a way for a server to say: 'The response body is the representation of the resource this URI'.
This is another great example of a HTTP caching feature in Ketting that goes beyond what Web Browsers typically do.
Other examples of this is being able to tease apart transcluded/embedded responses, allowing servers to invalidate caches for entries with an invalidates
link and exposing cache-related events to the user.
State
objects now have a .follow()
and .followAll()
function.
A State
object is returned when you (for example) call resource.get()
, resource.patch()
, etc.
This object represents an 'Entity' or 'State' returned from the server, which really is a fancy way of saying 'the body' + headers that directly pertain to the body.
It also provides direct access to hypermedia features such as links and actions. The new addition lets you follow hypermedia links straight from any HTTP response.
const response = await myResource.post({
data: {
param1: 'value1'
}
});
// If response contained a HAL, Siren, HTML link or HTTP Link header,
// we can follow it!
const newResource = response.follow('more-info');
Upgrading
Upgrading should be relatively pain-free for most users, except if you extend Ketting with custom format parsers.
If you run:
npm i ketting@7
npm i react-ketting@2 # React users only
And typescript doesn't complain, chances are that everything will work just
as before.
Ketting 7 has been in development and used by us in production since January.
Future plans
Long-term Ketting plans include
- Better documentation and educational resources.
- More React support, including a library of components for automatically rendering Hypermedia Forms/Actions and automatic paging of collections.
- Bindings to other frontend-frameworks.
- An official Websocket add-on, to enable real-time multiuser collaboration and bi-direction state updates.
Top comments (0)