Mar 25, 2021
Guidelines for Designing Web API
A complete checklist to follow before designing any Web API
Designing a Web API is a very common thing among programmers and everyone already knows and follows the standard to design one. You can also find many helpful guides on the internet on designing a web API and best practices around it.
The idea behind this article is to have a summarize checklist in the form of bullet points that covers every aspect of designing a web API so that anyone can just go through it once before designing any new API and doesn’t miss anything. I have created this checklist after reading the book Designing Web APIs by Orielly and everything below is extracted from this book, so if you find this list helpful or need more detail, you can always refer to this awesome book.
✓ Validate API Paradigm
1. Define business objectives
2. Decide, is it a Request-Response API or an Event-Driven API
3. Focus not on exposing your company’s internal infrastructure but on the experience that an outside developer should have when interacting with your API
4. The API should enable developers to do one thing really well. You have to be clear on what the API is not going to do as well
5. Design for today, and leave a small door to step through for tomorrow.
6. Present some use cases to better design the API
As a [user type], I want [action] so that [outcome]
✓ Design Great Developer Experience:
1. Make It fast and easy to get started
2. Work toward consistency for eg endpoint names, input parameters, and output responses
3. Write good documentation.
4. Create a sandbox environment for testing
5. Create SDK if possible
6. Developers should be able to try your API without signup or with minimal requirements
7. Show examples of inputs and outputs
✓ Make Troubleshooting Easy:
1. Return meaningful errors
2. Organize and categorize errors
3. Use of error code to handle errors programmatically
4. If you return a JSON response on a successful request, you should ensure that the error is also returned in the same format.
✓ API Security
1. Implement authentication and authorization mechanism
2. Implement Webhooks Security
✓ Scaling APIs:
1. Find the bottlenecks — check disk I/O, check network I/O, check CPU inefficient code, check memory
Performance profiling is one of the best ways to identify your bottlenecks
2. Add computing resources — vertical scaling, horizontal scaling, data sharding, data replication
3. Add database indexes
4. Implement caching mechanism
5. Do expensive operations asynchronously
6. Introduce new data access patterns
7. Support bulk endpoints
8. Add new options to filter results — Search filter, date filter, order filter, options to indicate which fields to return or not return
9. Paginating APIs — Offset based, cursor-based
10. Rate-Limit APIs
✓ Managing Change:
1. Automate testing to check backward compatibility
2. Write API description languages
3. Communication plan for developers — RSS feed, API docs, annotate response payloads, deprecation timeline
4. Version your API — In URI, HTTP headers, request parameter
Thanks for reading. I hope this was helpful and will serve the intended purpose. If you have any questions, feel free to leave a response.
