Last week we looked at JSON Schema
and how it can be used it in describing the data of your API. In this post
we’ll be looking at the
JSON Hyper-schema. It is a schema built on top of the
JSON Schema and describes the URLs that can be built with a given resource.
Let’s look at how we can use this spec to help supplement our APIs.
Like last time, let’s work with an example. Here is the schema similar to the one from the last post:
Here is how we can enrich this with the hyper-schema spec. With this schema we have defined how to update the data, where to get the friends list, how to add a friend, and lastly how to delete the person.
This is a great way to describe to clients how it can interact with your API in
a way that can be automated. While a lot of clients still don’t use it much you
can use the
Link header of HTTP to point to these.
I like to think of this as “CSS for your API”. It describes to the client how it can style the data with links to more resources. Not many clients understand this yet; however, with companies like GitHub using it for things like pagination it feels like adoption will only get better as time goes by.
JSON Hyper-Schema is very extensive and we’ve only covered a small part of
it. It also makes provisions for media-types and URI validations. If you want
to read more in depth on the subject I recommend heading on over to the
json-schema.org and reading up more on it.