API Design Principles

Victor Osimitz

Slice Technologies

What is an API?

• An API is a channel over which distinct software components interact with each other

• A good API is a clean façade in front of the underlying implementation

– Abstracts away complexity and messiness

– Decouples clients from the service

– Allows for flexibility in the underlying service

• API: Application Programming Interface

The Power of an Interface

ImplementationsInterface

• Completely different implementations, but a consistent, familiar interface.

• What if we change the interface?• Drive on the opposite

side of the road?• Manual transmission?

When designing a system, get the interfaces right, even if you get everything else wrong.

Typical Client-Server Architecture

• Data models vary wildly

• Multiple servers behind a load balancer

• Basic data operations: retrievals, adds, edits, deletes

• Fairly small set of errors

• May or may not require authentication

Principles of RESTful APIs

•Representational State Transfer

•Based on HTTP, which powers much of the InternetREST

•REST APIs are organized around data rather than actions

•Slice resources represent the data for a particular user: orders, items, etcResources

•Since requests will hit different servers, each request stands aloneStateless

•Standard HTTP actions and errors

•GET, PUT, POST, DELETE with standard meaningsUniform

•The entire data model should be accessible from only a few specified entry points

•Reduced dependency on documentationDiscoverable

A Few Standards

• JSON: flexible, lightweight data format (some XML)

• Instance: a resource representing a specific object, e.g. “order 123”

• Collection: a resource representing a group of objects, e.g. “all orders”

• HTTP Verbs– GET: retrievals– PUT/POST: full-object write– DELETE: deletions– PATCH: overwrite a field

• Standard HTTP codes:– 200: we’re cool– 300: ask that guy over

there (redirect)– 400: you screwed up

(request error)– 500: we screwed up

(server error)

Pragmatic REST

Make reasonable modifications when they make life easier for the API consumer, otherwise stick to REST principles.

Takeaways

1. Interfaces matter.

2. In your API, focus your energy on the data model. Use standards for everything else.

3. Break the rules if and only if it makes life easier for the API consumer.