The REST API Design Checklist
Here are some techniques that you should consider employing when you’re designing and implementing a RESTful web service. These techniques help in eliminating redundant code and allow easy introspection and security.
1. Versioning
Version your API at the top level so that you exactly know at any instant, how is your customer base distributed. This also allows you to alter functionality per version to encourage users into upgrading. A simple technique to version your API is to have version number in the URL path. For example: /api/1.0/getData.
2. Automatic latency and execution monitoring
Use aspect oriented programming constructs to mark your API entry points. Thereafter, automatically calculate the execution times and response types (success or error) in your aspect. This data can be quickly logged into a dedicated log file and processed periodically to create interesting graphs that can show you the health of your system at a glance.
3. Retriable APIs
Develop markers or annotations to mark APIs that can be retried in case of a failure. Users of this annotations should be able to specify the number of times to retry and the the strategy to employ, example, retry after a fixed delay, or retry using an exponential backoff strategy.
4. Decouple data access layer with the business logic layer
Typically your user facing REST service should have all the business logic required for an API to function. There should be another non-customer facing service that deals directly with your data store and performs CRUD operations keeping database constraints in mind. Your frontend REST service should call the backend data access service to get its job done. This makes the APIs more testable and promotes separation of concerns.
5. Identify critical and non-critical dependencies
Any API should very easily be able to enumerate its critical versus non-critical dependencies. If a critical dependency is down, the API can fail fast and return a failure. If a non-critical dependency is down, it can log warnings and continue the business logic.
6. Hide unused data from response
If a REST API is fetching a large amount of data from the data access layer, and returning a document JSON, it should be very easy to enumerate what data is not being used. Once identified, the attributes that are not being used should simply be stripped off from the response, either explicitly or using an after aspect.
7. Concurrent API calls
The implementation of an API should make it easy to reason about what happens if the API executes concurrently on multiple hosts. Its a bad idea to rely on only the HTTP header values, for example ETAGs, to decide which calls should succeed. The service implementation should employ better techniques like conditional writes while dealing with concurrent updates, instead of relying on eventual consistency.
8. Caching
APIs that take a long time to execute might benefit from some sort of a cache. Creating individual in memory caches on each host might not give you all the benefit of caching. A better design is to use a distributed caching service like memcached which any host can read/write into. AWS’s Elasticache service essentially provides a hosted memcached solution in the cloud.
9. Access control and authentication
Develop markers or annotations to easily mark an API as authentication-required or not. Another segregation within the APIs is whether the API is available to public or is for internal use only. Adding these annotations should also provide a context object with information about identity of the caller and location of the caller.
10. User profiling
Markers or annotation that identify API entry points, should also automatically categorize requests into highly granular buckets based on the user-agent or other request context that the client is reporting. This data can also be logged immediately and be processed periodically to create interesting graphs.
Do you think I have missed something that helped you in designing your RESTful web service?
