Category: HTTP API

RESTful JSON: Adding Links to your APIs

Derek Comartin Leave a comment

RESTful JSONThere’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.

  1. JSON objects MAY include a url property to indicate a link to itself
  2. 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 on Twitter

Software Architecture & Design

Get all my latest YouTube Vidoes and Blog Posts on Software Architecture & Design

Self Descriptive HTTP API in ASP.NET Core: Hypermedia Clients

Derek Comartin 6 Comments

This post is in my Self Descriptive HTTP API in ASP.NET Core series. It demonstrates how to design an HTTP API like a regular HTML website. This specific posts covers hypermedia clients.

If you’re new to this series, here are earlier posts to get up to speed:

If you have any questions, please follow me on Twitter.

Follow @CodeOpinion on Twitter

Hypermedia Clients

My perception is that most people new to hypermedia driven APIs think that consuming hypermedia happens via a magic library.

Or via some code generation that ultimately gives you a client library that understands every endpoint.

I’m not sure why this is, possibly the client code gen libraries behind SOAP/WSDL or Swagger/OpenAPI.

In my experience developing and consuming a hypermedia driven API, there is no magic.

Your consuming client needs to understand the content beyond just the media type for a given URI.

In a custom application, you likely want to show the user specific actions within the UI depending on if the link or action is returned in the API payload.

In our Todo application from my HATEOAS post, the action of marking a Todo item as complete was conditional.  It wasn’t available on every Todo item.  My UI would likely reflect that.

The same goes with links to other resources, they may or may not be in the payload.

Siren Browsers

However, you can make a generic UI if you use a defined media type.

Since I’ve been using Siren in my previous examples, we will keep with that for a client examples.

These Siren browsers are no different then HTML browsers.  They understand the media type and render UI.

What this shows is the ability for you to create re-usable components based on the specifics of the payload your server is returning.

In my Todo example, I could create a specific UI component that is used when retrieving a Todo item from the API.

Siren Client Helper Libraries

You technically don’t need any libraries to start consuming a siren payload.  As long as you understand what content inside the siren schema is going to be returned you should be able to deserialize the JSON into your own type and do what you want.

Super Siren is a pretty good example of a Javascript helper library.  It has helpers for making HTTP requests and then performing navigation and actions.

Next

Looking ahead I will start to develop our ASP.NET Core client.

As well as discuss why why URLs become opaque.

Meaning there is no difference between

http://domain/api/todo/123

and

http://domain/cf2b6d63-9a7f-4dc6-9989-f12bb8af7715

If anyone has any other suggestions or recommendations about this series, please leave comment or let me know on twitter.

  1. Building a Self Descriptive HTTP API in ASP.NET Core
  2. Object as Resource
  3. Hypermedia
  4. Siren
  5. HATEOAS
  6. Hypermedia Clients

 

Follow @CodeOpinion on Twitter

Self Descriptive HTTP API in ASP.NET Core: HATEOAS

Derek Comartin 1 Comment

This post is in my Self Descriptive HTTP API in ASP.NET Core series. It demonstrates how to design an HTTP API like a regular HTML website. Bringing the concepts of links and actions to your API allows your clients to consume it with ease.

If you’re new to this series, here are earlier posts to get up to speed:

If you have any questions, please follow me on Twitter.

Follow @CodeOpinion on Twitter

Actions

In my last post I covered outputting a siren hypermedia payload from our ASP.NET Core MVC application.  Specifically I showed linking to each Todo item within the collection.

One aspect of Siren that I mentioned I like is it’s ability to specify actions.  This is important for me because it’s what I first started thinking about when working on my most recent HTTP API a couple years ago.

I needed to the ability to tell the consuming client (Angular) about subsequent actions it could take.

Workflow

Wanting to describe actions in our API responses revolved around permissions and workflow.

For example, if the requesting user didn’t have permissions to perform a specific action, I wanted them to know it. Having this information within the content of your response, we could make the client show or hide certain aspects of the UI depending on the response it received.

Same goes with workflow.  Depending on the state of the system, we could conditionally send down links and actions (commands and queries) through our responses to the client.

Dumb Clients

This made our consuming clients really dumb about workflow.  The knowledge about when an action can be performed based off the state of the system was determined by the server.

This is my biggest issue without using hypermedia.  Is that the client must understand when it can make calls to particular resources.  Meaning it must understand workflow.  For me this was incredibly problematic as some of the workflow is non trivial.

This logic already existed on the server for validating if a command/request could be executed based on the current state of the system.

Demo

I realize this is a trivial demo, but I hope it gets the very simple idea of the server defining the workflow.

We are going to create another converter for a single Todo.  We will provide Actions which allow the client to delete or mark a Todo as complete.

Once a Todo is complete, that action is no longer relevant.

When we access the resource for an individual Todo item, we end up with the following siren payload.

HATEOAS

If our client were to then make a call to the complete action, its response, along with any additional call to the previous GET endpoint results in the complete action no longer being returned in the payload.

HATEOAS

Hypermedia as the Engine of Application State

This is really what links and actions are all about.  Guiding the client to various resources in your API based on the state of the system.

You may of also heard of this with the horrific acronym of HATEOAS.

Regardless, I find the concept incredibly powerful for guiding clients down a path based on the state of your system.

Source

All the source code for my demo is available on GitHub.

Looking ahead we will dig into developing clients consuming our API and the (not) versioning.

If anyone has any other suggestions or recommendations about this series, please leave comment or let me know on twitter.

  1. Building a Self Descriptive HTTP API in ASP.NET Core
  2. Object as Resource
  3. Hypermedia
  4. Siren
  5. HATEOAS
  6. Hypermedia Clients
Follow @CodeOpinion on Twitter