RESTful JSON: Adding Links to your APIs

Sponsor: Interested in learning more about Distributed Systems Design? Enter for a chance to win a 5 day Advanced Distributed Systems Design course led by Udi Dahan founder of Particular Software, and creator of NServiceBus.

There’s a new media type available, RESTful JSON, that was recently registered (Feb 1st 2018) with IANA. It’s really the simplest possible media type to use in order to start adding links to your JSON APIs. The new media type is application/vnd.restful+json

Adding Hyperlinks

The simplicity here is that you can start using this media type with existing APIs to start adding links to your existing objects.

JSON objects MAY include a url property to indicate a link to itself

JSON objects MAY append _url to properties to indicate related links

Example

Here’s an existing payload of a e-commerce shopping cart. It has one product in the cart.

Now we are going to add a couple links. We are going to add a link to the product in our cart to the product page, and add another link to provide the URI for the checkout page.

Runtime

Links are to be used at runtime by your client. Meaning the presents or absence of them will determine how your client behaves. With links provided in the API, you can now traverse the payload at runtime rather than hardcode URIs. Are you using a hypermedia content type? I’d love to hear your comments or on Twitter.

Follow @CodeOpinion