Encouraging public API consumers to use Hypermedia

I’ve had a lot of great discussions at API Strat this year and it has inspired me to get back into writing. In the near future I’m going to convert my API World talk into a blog post and discuss some of my upcoming projects. For now, I want to lay out my thoughts on encouraging public API consumers to use hypermedia. To do that, I need to walk through three quick questions.

1. What is the goal of hypermedia?

There are many different reasons to use hypermedia but I think the most immediate goal is to reduce an API consumers dependence on hard coding their API actions. By allowing your API consumer to find these actions in an API response the server can manipulate the availability and implementation of these actions on the fly.

2. How do developers discover new features on your developer portal?

Do they come to a developer site looking for the “/me/likes/{video_id}” endpoint or are they looking for “how to like a video”?

I see a lot of reference docs falling into this pattern and use a URL path as the title of a segment of documentation

PUT /me/likes/{video_id}

I think the documentation can be quickly improved with some organization and copy improvements.

Like a video

New users don’t know if your API is GraphQL, REST, GRPC or so on. New users have a problem they need to solve and the documentation explains how to solve that problem. We shouldn’t assume they have any knowledge of your URLs.

(Quick shout out to Keen.io who does this well: https://keen.io/docs/api/?shell#get-project)

3. If an API feature is not documented, does it exist?

I would argue no. A new user finds a feature by searching through documentation, they are not randomly testing URLs. If someone does find a hidden URL I don’t believe they should have any expectations of reliability or stability. If you want to treat these random-url-finders with a little more respect you can consider stricter access control protections such as URL signatures.

The Theory

Let’s recap

  • Hypermedia is about encouraging users to use in-response actions instead of hard-coded URLs
  • New developers learn about an API by researching the problem they are trying to solve and the actions they might take to solve that problem. These users do not go to your documentation and start looking for a specific URL
  • Undocumented features don’t exist

If we believe all of these ideas, let’s stop documenting any URL associated with a hypermedia control. Let’s treat those URLs like they don’t exist. Following this theory, what do our docs look like?

Like a video

Or if we want the content to be a little lighter and focused on a quick reference it might look like this…

Like a video

Real world examples

Vimeo has one (accidental) example of success with this strategy. Video uploads are documented here.


  1. POST /me/videos, grab the upload_link and complete_uri from the response
  2. Send your video data to the upload_url
  3. When the upload is complete, make a DELETE request to to the complete_uri

By leaving the URLs associated with the upload_url or complete_uri completely undefined, we have been able to encourage this link driven workflow for all API consumers.

Has anyone attempted this? I would love to hear any thoughts or experiences in the comments or on Twitter.

API Product manager by day, and web developer by night. This blog is primarily a collection of thoughts on all things API

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store