Pooja Mistry is a developer advocate at Postman. In this article, she discusses designing APIs that stand the test of time.
Postman is an API platform that has over 25 million users worldwide. Postman is a tool that helps teams work with APIs more effectively.
We’re moving towards an API-first world. APIs are the cornerstone of most of the technologies that we have available. With Postman, we believe that the platform is for both the creators and the consumers of APIs. We wanted to build a platform that supports this trend.
With code-first development, you can start with the core code functionality. And then, when you’re done, you’ll probably need to create an API to build your first web app. You may need to create apps to support your users. Some of them may be internal users, and some may be external. So, you may need microservices or different sets of APIs. This can lead to a disconnect.
With API-first, you’re thinking about your consumers first. Then, you’re working with your engineers to apply your API to those consumers, paving the way for other platforms and services. So essentially, with API first, what you’re trying to do is that you’re trying to design it based on your consumers’ use case instead of building it first and designing it later.
API-first is an organizational mindset that allows you to think about an API development model in which APIs are designed before implementation. The API first strategy involves many building blocks to create solutions or products that can save time or money and generate additional value.
Eight traits of an effective API-first design
- Alignment with an organization’s goals – The API you build has to have some sort of purpose and achieve something. So, it must be aligned to whatever your organization is contributing to.
- Reusability – Ability of the API to be used on multiple different applications
- Interoperability – The ability of an API to be used across many different teams
- The ability to evolve – Ability to enhance that API with new or existing features, making that API adaptable to change
- User-friendliness – User-friendliness allows users to interact better with the API and reduces the time to the first call.
- Security – Security is always a big concern when it comes to web APIs and what operations are exposed to whom
- Efficiency involves the performance of an API
- Pragmatism involves solutions that can be too tricky or compliment to implement.
Impact of API Experience
There are three types of APIs – public, private, and partner. The impact of a good API experience can lead to more usability, reusability, and time to value APIs. It helps create APIs that evolve smoothly and have fewer risks of introducing breaking changes. A bad API can lead to higher costs and decreased productivity. It takes longer for integration and shifts in delivery dates.
Public APIs are available to everyone worldwide to consume, whereas partner APIs are exposed to strategic business partners. Private APIs are more internal, and they’re hidden. With an API-first approach, understanding the users’ needs leads to a better experience.
Better practices for good API designs
- Naming
- Data Modelling
- Required / Not Required
- Error handling
- Documentation
- Consistency
With these things in mind, you can ensure that your API lasts and is available to stand the test of time when it comes to interoperability and meeting those eight cases of API-first strategies.
Open API Specification is a machine-readable and human-friendly API description format. It describes REST or an API in a RESTish fashion. It uses JSON schemas to describe data and is written in JSON or YAML. It is vendor-neutral and technologically agnostic. Within Postman, we have the Open API definitions as a part of our API builder.
Consider that we want to get a coffee. This is the “What”. The APIs (which are the steps) would be “Choose coffee beans” and “Brew coffee.” So, these are two different types of APIs. We can understand who the users are, what they can do, how they can do it, what inputs they might need, and what outputs they will get eventually. The API goal Canvas allows you to work with those API strategies to understand your users better. We ended up creating two different types of APIs: a Get API, which allows you to choose one of the beans before brewing the coffee, which is then reflected in our Post Brew API, which allows you to get the coffee eventually.
While designing APIs, we thought of different design concerns. And the first concern that we thought about is Naming. Naming is a crucial aspect of building an API that stands the test of time. Consistent naming conventions can make your APIs easy to use and understand. Naming should be consistent at every level, including endpoint names, method names, response codes, etc.
The other aspect is data types. APIs that use data types define the structure of data sent or received by the system. Without proper data typing, many errors can be used and interpreted regarding incorrect outputs or unintended consequences. It should provide consistency, ensuring that the right data types are returned for your APIs and not confusing them with other data types.
One more aspect is required or not-required parameters. Required parameters are the parameters that must be included in an API request to receive a valid response. They’re essential for ensuring an API can process the request and provide accurate data. In comparison, the non-required parameters are optional and not necessary for the API to function properly. You want to think about the parameters that are most required, the minimal viable, required parameters, to get somebody to hit your API endpoint successfully, also ensuring that they’re getting the right amount of information back.
This leads us to the aspect of error handling. Error handling is often overlooked. When your API is not set correctly, you can send a generic error message to the user, making it difficult for the user to use your API. Sending the right error messages back to your users allows them to work with that API, fix their issues, and ensure they can get a proper response.
To conclude, I hope this gives you more insight into working with APIs and using the best practices better.
