Hypermedia APIs vs. Data APIs

Introduction

A hypermedia API is an API that returns hypermedia, typically HTML over HTTP.

This style of API is distinguished from data APIs that do not return a hypermedia. The most familiar form of this latter style of API today is the ubiquitous JSON API.

These two different types of API have distinctly different design needs and, therefore, should use different design constraints and adopt different goals when being created.

Hypermedia APIs:

  • Will be trivially REST-ful, since they are simply what Roy Fielding was describing.

  • Should be driven by the needs of the underlying hypermedia application

  • May change dramatically without versioning information, because hypermedia utilizes self describing messages

  • Should be passed directly to humans, to maximize the flexibility of the system

Data APIs, on the other hand:

  • Will not benefit dramatically from REST-fulness, beyond perhaps Level 2 of the Richardson Maturity Model

  • Should strive for both regularity and expressivity due to the arbitrary data needs of consumers

  • Should be versioned and should be very stable within a particular version of the API

  • Should be consumed by code, processed and then potentially presented to a human