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
- Identify the resources (Nouns): Create, Retrieve, Update, Delete (CRUD)
- Mapping activities to resource lifecycle (map actions to HTTP verbs and nouns)
- 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
– 200 OK
– 201 Created
– 202 Accepted
– 204 No Content
– 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.
– 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>