In the last two JSON-Hyper Schema articles (Getting Started — Part One and Part Two), we covered the basics:

  • Basic Links
  • Request and response bodies
  • Request and response headers
  • HTTP methods

But while working with JSON Hyper-Schema I have discovered a couple of common API patterns that could use a little more explanation.

In this article I’m going to show you common hypermedia patterns and how to describe them with JSON Hyper-Schema.

Hypermedia for Collections

When you are handling a collection of items, such as a list of users, there are two forms of hypermedia you want to think about: the hypermedia associated…

In my last article I described how JSON Hyper-Schema can describe basic links. This included…

  • The basics of JSON Schema
  • Describing links with Link Description Objects (LDOs)
  • Automating URI construction with URI templates, templatePointers, templateRequired and hrefSchema
  • Reducing schema duplication with schema references

In this article I’m going to build on that foundation with resource representations, arbitrary request bodies, HTTP headers, and HTTP methods.

Describing resource representations

Interacting with a resource via it’s URI often involves a resource representation. The most common time you see a resource representation is as the response of an HTTP GET request.

In JSON Hyper-Schema a resource representation…

JSON Hyper-Schema is close to becoming an official spec, so let’s see what it’s all about.

JSON Hyper-Schema is a format for describing an API. You can automate a lot with a document that describes your API.

  • API SDKs
  • Documentation
  • Tools such as API sandboxes or Postman collections to simplify the development process
  • Contract tests to ensure your API doesn’t change unexpectedly
  • Mock API servers to test your design before building the API

OpenAPI is another API description format, but whereas OpenAPI usually remains content with server-based uses, clients can use JSON Hyper-Schema directly. A client can use this schema…

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…

Hey everyone,

In September I attended REST Fest and API World. Here’s a couple of presentations I enjoyed, and links to my own talks.


Adam Kliment showed a cool little project called “Restful JSON”. Restful JSON is a formalized naming convention for URLs in JSON. I’m a big fan of standardizing small, composable pieces of JSON. Maybe next we can standardize forms or pagination.


Joshua T. Kalis discussed LuxUI which tackles the idea of a generating a web UI from hypermedia controls. I love seeing more people explore this idea. …

Your API is a long-term promise.

I promise that my API actions, and how they behave will work as described in the documentation.

This promise is hard to uphold. Time isn’t explicitly defined in that agreement. The API creator may think they can change their API whenever it’s necessary. The API consumer probably thinks the API will remain the same forever.

These two assumptions directly oppose each other.

APIs that want to iterate and improve their product could email all of their consumers, asking them to update their integrations. But what if those companies don’t have full-time software engineers on…

If you are working with JavaScript, there’s a good chance that you have a ton of promises or callbacks nested over and over again. Promises helped me clean up the numerous callbacks, but coroutines really took it to the next level. Coroutines allow you to remove callbacks entirely, and write asynchronous code that looks completely synchronous. In a couple of quick steps, I’ll show you how to simplify your promise-based code by converting to coroutines.

Note: This article briefly talks about generators. If you would like a more thorough description, check out my article on generators!

Let’s start with an example

Here’s an example using…

Generators were introduced in ES6, and are available on these platforms. While I have not used generators in the browser yet, I use them heavily in server-side iojs.

Why should I care?

In my opinion, the number one reason to use generators is to clean up asynchronous code. Generators can also be used to create array-like objects, but their interactions with promises are incredibly powerful. This article will explain generators; a future article will explain how it applies to cleaning up asynchronous code. For now, I want to take you through the unique ways in which generators differ from normal functions.


First things first…

It took me way too long to figure out how to get S3 cors headers working, here are my notes.

  1. In the S3 interface, click the magnifying glass icon to the left of your bucket.
  2. Click the “Edit CORS Configuration” button. It should be right next to “Add Bucket Policy”
  3. You should already have a CORS XML file in here, if not mine looked like this :
  1. This CORS header allows all websites to perform GET requests against this resource.
  2. To reference the file, you must use the url structure [bucket][object]
  3. If using an img tag, it must contain the attribute crossorigin="anonymous". Read more here:

Check out MDN for more information about CORS headers.

Originally published at

Yesterday I launched Bifocals.js, a node library for handling http responses.

It was my first big launch, and I learned a ton from it. Before I go into that, lets show some numbers.

  • Peaked at # 9 on Hacker News
  • 7,077 Page Views
  • 6,202 Unique Visitors
  • 56% United States
  • 70% Chrome
  • 48% Mac
  • 87% from
  • Avg. Visit Duration: 00:00:17

That visit duration is abysmal. Clearly the docs need to be improved.

I received the best discussion via Facebook, and then Hacker News. No one initially knew what the hell my library did. …

Aaron Hedges

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