Chapter 5. Guiding principles for API design
- API design principles for successful APIs
- Cautionary notes on design antipatterns
- API examples highlighting these principles
The technical aspects of REST APIs are only part of the puzzle. This chapter and the next few focus on the process of creating an API that’s not only functional but also delightful and usable.
Before I get to the meat of the process, I want to give you some advice to keep in mind during the process. This is definitely not a checklist; even when you’ve already done one of these things, you need to continue doing it. Think of it as learning to drive a car—even though you’ve checked your blind spot once, you need to continue doing so as you move forward. Similarly, this chapter is designed to help you create a mind-set while you go through the API design and development process that will help you make the right decisions to achieve success. I discuss the guiding principles of API creation and ideas to keep at the front of your mind while going through the steps to create your API.
- Don’t surprise your users.
- Focus on use cases.
- Copy successful APIs.
- REST is not always best.
- Focus on the developer experience, not the architecture:
- Communication and consistency are critical.
- Documentation should tell a story.