API Best Practices
An Application Programming Interface (API) provides a programmatic interface to a Service. They have been used since the early days of programming to define how one part of a system talks to another part. In the era of smart Web Applications, Native Mobile Apps, Smart Devices, and Integration, APIs that use Web standards have become much more prominent and significant. Over many years of API design and implementation, I have learned a few lessons, many the hard way. What follows are some Best Practices to consider when working on your next APIs.
- The API is a First-Class Citizen in the Architecture
The API/Service exposes a company’s business logic and data. Consider it the center of your solution design. Sure, all the User Interfaces are important, but their job is to provide a pleasing and appropriate experience on top of the core API/Services’ exposed functionality.
- Low-Trust Relationship with Consumers
An API can have many different consumers ranging from web applications, native mobile applications, smart devices and external third-parties. None of the requests from these consumers should be trusted by the API. Validate everything; do not rely on the consumer to verify things. Check all business logic and dependencies. Keep in mind one of the consumers of the API may be a hacker with a stolen password. The API is the gatekeeper for a company’s services and data and should be implemented as such.
- Move to a Microservices Architecture
Microservices is just the latest term for good service design. It advocates the use of small, independent services. A common design pattern is to have each service cover one subject area (e.g. customer, order, etc.) but other patterns also work. The smaller services are easier to maintain and it’s easier to avoid the “big ball of mud” that happens with large, monolithic systems. Each service can be separately scaled as the demands of the system grow.
- Honor Service Boundaries
Each service has a well-defined API that should provide the only access to the service’s functionality. Resist the urge to call into the internals of a service because it’s convenient. This restriction can sometimes lead to some interesting challenges with typical one-to-many relationships that cross service boundaries, but there are patterns to get around this. Letting one service have access to another service’s data (often through a database call) sets up a dependency that ruins most of the benefits of a well-designed service.
- Use Consistent, REST-based Conventions for Defining APIs
There are standard conventions for building REST-based APIs. Most API consumers know these conventions but if developers can’t understand, or don’t like your API, they won’t use it. You can find a reference to the most common naming conventions at https://restfulapi.net/resource-naming.
- Test APIs Independently and Thoroughly
Since APIs represent the exposed business logic and data for the company and act as gatekeepers on errand consumers and outright hackers, they should be thoroughly and independently tested. Have QA focus heavily on API validation using automated tests. Don’t ignore the UI, but be sure that if you made a typo somewhere in the bowels of your Angular Web Application, it won’t result in an API call that does something disastrous.
- Create a Version Release Strategy to Enable Backward Compatibility
Like all software, APIs get enhanced, fixed, and upgraded. If the changes are backward compatible with the previous release, then life is good. But sometimes a new release introduces a breaking change. In order to accommodate this, consider a versioning strategy that allows more than one version of your API to coexist with another, minimizing the impact to your consumers. If you plan for this by including a version number in your URL naming convention then you’ll be prepared if you ever need to use it.
- Organize Teams for API Development
Like good user interface design and development, good API/Service design and implementation requires specific technical skills. Consider a separate API development team, but be cautious as this may introduce delays on projects. A good rule of thumb: once a service becomes reusable across consumers, a separate team or set of team members should manage its growth to ensure consistency.
About the Author
Doug Gregory, Practice Director, PREMIOS
Doug brings nearly 30 years of experience and knowledge in the software industry to PREMIOS. As a Practice Director with the company, Doug oversees delivery of all custom software and integration projects.