Effective Design of RESTful APIs

API design is hard

– What functionality to expose
– How to expose it
– How best to expose it
– How to adjust and improve


Affordance in Practice

– What the API allows you to do?
– What the API makes easy?
– What the user wants to accomplish?


Three approaches to adding an API

1. Bolt-On Strategy:

This is when you have an existing application and add an API after the fact.
Brute force approach but generally fastest way to get something useful.
Takes advantage of existing code and systems.
Problems in the application tend to “leak through” into the API

2. Greenfield Strategy:

No underlying application or business logic that you have to interact with.
Complete freedom and flexibility to do whatever you want, however you want to.
Generally the “API first” or “mobile first” mindset.
Easiest scenario to develop an API.
Takes advantages of new technologies, possibly reinvigorate the team.
Not always possible to derive business value quickly or easily.

3. Facade Strategy:

Middle ground between greenfield and bolt-on.
Take advantage of existing business systems, yet shape them to what you prefer and need.

Step 1: Identifying Participants

These are the people who will be involved in our business process and using the API.
– who is involved in our business process
– directly or indirectly
– internal or external

Step 2: Identifying activities

– define the business processes or goals involved

Step 3: Breaking them into steps

Step 4: Create API definitions

  1. Identify the resources (Nouns): Create, Retrieve, Update, Delete (CRUD)
  2. Mapping activities to resource lifecycle (map actions to HTTP verbs and nouns)
  3. Map the remaining activities to custom actions – how resources are related?
    Designing Relationships – Three types
    1. Independent – the resources may exist regardless of the other existing but they may reference each other
    2. Dependent – one resource cannot exist without the parent
    3. Associative – they are independent but the relationship contains additional properties to describe it (Example: movies and actors)

Step 5: Validate your API

– Write each resource’s actions on notecards
– Use notecards to map out each flow, action, etc.
– Fill in any gaps you might be missing, assign them to resources as appropriate


HTTP Response Code Classes

1xx Informational

2xx Success

– 200 OK
– 201 Created
– 202 Accepted
– 204 No Content

3xx Redirect

– 301 Moved Permanently
– 302 Moved Temporarily

4xx Client Error

– 400 Bad Request
– 401 Authentication Required
– 403 Forbidden
– 404 Not Found

5xx Server Error


REST APIs: The six constraints

– Client-Server: Webserver and web browser, scalability and reliability
– Stateless: Each request stands on its own, requests can be processed in any order, login credentials with every request. Why Stateless? Because it gives flexibility, stability, reliability.
– Cacheable: each message should describe whether it’s cacheable, improves network and application usage, makes the system more reliable and scalable. GET, PUT, DELETE should be cacheable. POST should not be cacheable. etags can be used to inform the cache on what is cacheable and what is not. You will still some sort of cacheing mechanism like Varnish, Memcached, et cetera. You make a HEAD request to retrieve headers. If the etag in headers hasn’t changed, you can used the cached value. If the etag is changed, you need to send a full request. MD5 can be used to generate etags.
– Layered System: Should not be built on the assumption that it’s communicating directly with the server. Why? because it allows in between systems to add/improve functionality like load balancers, caches, logging, authorization, etc.
– Code on Demand (optional): A request doesn’t just retrieve a resource but also the code to act upon it. We don’t have to know or understand the code, just how to run it. Allows flexibility and upgradeability. Much of the internet already does it with Javascript.
– Uniform Interface: 
1. Identification of Resources: Each resource should be uniquely identifiable by a particular URL.
2. Interaction and manipulation of resources through these representations.
3. Self-descriptive Messages: if the resource is cacheable, how to process itself, how to request the next resource.
4. Hypermedia as the engine of application state (HATEOAS)

curl -l <URL>



Best Practices for Designing a Pragmatic RESTful API