Part II: Being RESTful with APIs
Now that you've defined your user flow, it's time to jump into the next step!
Basics of APIs, REST and HTTP
Imagine you need a bag of chips from a vending machine. You put in the cash, punch in a code and the machine spits out the selected product. As long as you have your chips, you don't need to know the inner workings of the vending machine.
APIs (Application Protocol Interfaces) work in the exact same manner. Think of it as a contract to exchange data between two software systems. Like an abstraction created over the system. The API will specify how and what data will be exchanged without actually caring about how the system works.
A simple CLI can be seen as an implementation for an API. After all, isn't it just an interface to interact with the system? Sure, there are other ways to design APIs too which include gRPC, GraphQL (more on that later). But for this series, we will be concentrating on REST as a concept to design an API.
REST
REST (Representational State Transfer) is the most popular architectural method used to design APIs. Mostly used for designing Web APIs, RESTful services are usually HTTP based and often use JSON as the standard data exchange format (although REST can be used over other protocols and also supports YAML, XML along with other formats).
We’re not going to go through the entire concepts around REST and HTTP. In a nutshell, the concepts are summarised in the image below. If you’re keen on knowing more check out the references at the end!
Designing Good APIs
Designing APIs requires deliberation because a lot of factors need to be considered during this process. The main focus here is the usability of the API. You must have an API that's easy to understand and use so that any developer can start using it within minutes
In summary, here are a few tips to design APIs.
User Experience for Developers
The most important aspect to ensure is that the APIs should be easy to understand and use. This inherently implies that there should be comprehensive documentation detailing the API usage and functionality. Hosting in sites like Swagger or Apiary ensures that there is a single source where the API documentation is available.
Error Handling
Each and every scenario for failure needs to be thought about and accounted for before development begins. Good error handling techniques that systematically describe the error along with its possible cause (and preferably a solution) should be in place.
Security
Since APIs act as an interface to the system, implementing adequate security measures is always advisable. Using authentication, security tokens, etc., are a few measures that will add an additional layer of security to the APIs to prevent any sort of compromise.
Accessibility
A good way to go is to host the API specifications for the developers to access. The developer portal should include all of the tools required to use the API. In an ideal scenario, the developer shouldn’t need to invest more than a few minutes reviewing the API before starting.
Optimisation
Different types of devices have different capabilities depending on the hardware specifications. So, if the consumers of the APIs include mobile devices too, then consider trimming down the API details depending on the form factor. Evaluate the pros and cons of performance and usability and optimise accordingly.
Moving forward, we'll actually design an API specification using Swagger and Open API Specification. It's really easy to learn and use. So, head over to the next post to know more!
New here? You might want to check out step 1 of this series before moving forward.