Design a beautiful REST API

Simon Wicki
Dec 4, 2013 · 3 min read

Every dev at some point has made decisions how his backend API should look like. If you’re coming from the web, then mostly for ajax calls. But what if that API should also address calls from other sources and clients.

To fill that gap i was watching an informative talk by Les Hazlewood about beautiful RESTful. I’ll cut this in several sections. This is merely an overview, the full coverage you can get from the youtube talk or the slides.

Endpoint Naming

  • Nouns, not verbs (No: getUser, Yes: /users/a1b2c3)
  • Parameters not in URL (hassle if changes arise

It should be divided into two fragments:

  • Collection (
  • Instance (


It’s a good thing to use different methods for calling the api. They don’t represent 1:1 the CRUD model. PUT and GET can be used for create and update.

  • GET: read
  • PUT: create, update
  • POST: create, update (partial update, due to quota)
  • DELETE: delete
  • head: headers, no body

Update / Create

Keyword here is idempotent. This means that it produces the same result if it’s been sent once or multiple times. To avoid having different states, the update should contain the full object in its entirety.

Partial updates can be done (using POST) if you’re concerned about your data quota.

You should give responses back for the PUT/POST:

Media Types

they tell the the server what format the client understands and prefers and how the client has to parse and process it.

  • Request: accept header
  • Response: content-type header

you can have your own media-type (application/json+foo), that has a defined specification or add additional parameters (application/json+foo;application) — see API Versioning for another possible use case.

API Versioning

In case you make drastic changes, you still want to support the old API, to prevent problems with old implementations. There are possibilities to do so:

  • URL:
  • media-type: application/json+foo;application,v=1


You want to retreive a resource, which contains other resources. Best practice is to provide an atomic resources. So you shouldn’t provide an endpoint as such, rather have seperate endpoints for each. In a JSON it would look as follows:

href: ‘',
name: ‘John’,
lastname: ‘Smith’,
address: {
href: ‘'

The result doesn’t contain the all address properties, but the href one, which tells the requester exactly where the resource is located.

Reference Expansion

In case you’d like to make only one request for the user and its address properties, you can provide an additional parameter:


You can also request more than one reference expansion separated by a comma. In case the property doesn’t exist, a good practice is to return a 409 Conflict.

Partial Representation

Usually you get all properties of a resource upon a request. You could list the wanted properties in a request like this to save bandwith:



On Collection calls you may come across a lot of items that shouldn’t be requested all in one call. A possible pagination request could look like this:


The returning JSON could look like the following:

offset: 0,
limit: 25,
first: {
href: ‘'
previous: null,
next: {
href: ‘'
last: {
href: ‘'
items: [


Sometimes errors should tell the API caller more than only a return code, then this is a good way to do so.

  • as descriptive as possible
  • as much information as possible
  • if your API is targeted at other devs, provide additional dev info
post /users
409 conflict
status: 409,
code: 40924,
property: name,
message: ‘user named xyz already exists’,
developerMessage: ‘user named xyz already exists. if you have a stale local cache, please expire it now’,
moreInfo: ‘http://…’


  • should be opaque
  • should be globally unique
  • avoid sequential numbers
  • good candidates: uuids, url64

What the talk covers additionally

In the 1h 25min talk, Les Hazlewood covers other topics. Hop over, if you’d like to know more about these sections:

  • Base URL
  • Many to Many
  • Return Values
  • Method Overloading
  • Caching & Etags
  • Security
  • Multi Tenancy
  • Maintenance

    Simon Wicki

    Written by

    Former Head of Frontend at @JustWatchcom. Co-organizer of @IonicBerlin. Creator of Notyfy. Book lover.

    Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
    Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
    Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade