With API First approach gaining more traction it is very important to emphasise on good API Design. Designing a good API is more of art and iterative process.It is critical to put the Users first and spend a lot of time on refining the APIs.
A few years back APIs were considered to be just a software interface to connect disparate system to achieve a business capability. This was the bare minimum expectation but over the years this has increased to leaps and bound.
Based on API 360 model, an API design should consider the following
- Usefulness - Does it address any relevant Business problem.
- Engagement - Is the API easy to adopt and how good is the Developer Experience
- Evolvability - Can it address the future requirement like support more users, different regions, etc
- Security - Is it secure and manageable
The key considerations the designer has to keep in mind when designing an API are
- Who are the users of the APIs
Are the intended Clients internal or external to the organisation. Based on AWS API Mandate, an organisation should not build different set of APIs to cater for internal and external usage. Internal APIs should be build with the consideration that it should be able to support external traffic with few controls in place.
- What is the business problem the API is supposed to address
Identify the API type based on the capability it is expected to support
API types falls into 3 main categories
- System API - API to support simple CRUD operation
- Process API - API to support interaction among different system, eg Generation of Consolidated Bank Statement
- Experience API - Typically custom made for external users
- Does the API handle any sensitive data
Proper encryption and encoding should be considered when handling sensitive data.
- Is it a global or region specific API
If the business process is region specific then building a single global API to handle all regions requirement could be an overkill and it is better to build region specific API and weave them together as Global API. For eg introduce an HTTP header to specify the market or region and the Global API would just do the routing to specific region.
A few best practices to consider when designing an API
- Avoid jargons in API URL and field names
- Use HTTP Methods and Resource to define the URL
- API fields must be least restrictive
- The API Response must reflect the resource mutations
- Use Enums instead of Boolean
- Timestamp field naming should be <<verb>>ed_at format
- Currency should be used to represent amount fields
- Consistent way to search and list results
- Use Nested Object instead of flat structure
- Error Codes must be consistent across end point
- Use consistent Authentication mechanism
- Consider the throttling and rate limiting parameter
- Leave place holders for Sunset headers
- Strive to make any changes to API as backward compatible
