Your API program will see more success with a thoughtful API design phase. Effort spent on architecture often returns as time saved during other phases of your project. These efficiencies add up across the hundreds or thousands of APIs you support.
Your API design should be backed by your company’s strategy and focused on real use cases. By looking to industry conventions and defining company patterns, you’ll provide clarity to API consumers and designers alike.
Understand the Problems Your API Solves
Before you can design any solution, you need to know your goal, or at least the issue your design addresses. Your company, group, or product’s strategy will lead the decisions you make during the API design phase. When you understand the problems your API solves, you’ll make informed decisions about how the interface should be designed.
It’s technically possible to create non-strategic APIs. You can copy an existing database model and expose basic operations as an API interface. However, this approach skips API design completely.
You need to understand the use cases your API will support. What do API consumers need to enable? How will end users experience the software powered by the API? These questions may seem simplistic, but the answers are foundationally important.
Adopt Industry Conventions for Your Interfaces
When a web designer creates a website, they start with the basic idea of a web page. Similarly, sports car designers and wedding dress designers each use their field’s expectations as a constraint. Your API designs should rely upon industry conventions as a starting point. You probably don’t need to get creative with security, data formats, or other decisions.
Your API architectural style will determine some of these conventions. For example, the URI-based approach familiar to many developers has many patterns you can use. To start, your endpoints should be based on resources and your HTTP methods are actions taken upon each resource. You’ll find conventions for many common aspects of your architectural style.
For many APIs, you’ll use OAuth and/or other common security schemes. You’ll return responses as JSON or XML. Unless there’s a design reason to do otherwise, adopt conventions. These help your API consumers quickly become familiar with your interface.Pursue Consistency Across Your API Program
Pursue Consistency Across Your API Program
Just as conventions provide a good developer experience, so does consistency of your API designs. You want to remain uniform within a single API—avoid varying approaches from endpoint to endpoint. Wherever possible, adopt an organization-wide or business unit API style guide for others to follow.
If your API use case includes pagination, for example, be sure you implement it consistently. Each endpoint of the API with pages of results should use the same approach. If possible, your organization’s other APIs should adopt the same paging method. And it should be based on one of the few industry conventions for pagination.
These few API design best practices will enable your company to build strategic APIs. In addition, their conventions and consistency will make them easier for developers to use, translating to greater efficiency in your engineering teams.