Table of Contents
Open Table of Contents
Introduction
A web API (Application Programming Interface) is a set of programming instructions and protocols used to access a web-based software application or web tool. In simple terms, it is a set of rules and protocols that enable different software applications to communicate and share data with each other over the internet.
Stateless API calls
An API call is considered stateless when it can be made independently from all other requests, with no additional context or data whatsoever e.g., ask for the weather based on the postal code.
Stateful API calls
A web API that stores a user’s favorite cities and provides weather forecasts for those cities requires a user to already have stored the cities, so we can consider an API stateful if:
- It involves other prior requests
- Or previously stored data
Resource-oriented APIs
This kind of API provides a standard (limited) set of building blocks. Rely on the idea of “resources”, the key concepts we store and interact with.
| Name | Description |
|---|---|
Create<Resource>() | Allow us to create a new resource |
Get<Resource>() | Allow us to get a single resource |
List<Resources*>() | Allow us to get a list of resources |
Delete<Resource>() | Allow us to delete a resource |
Update<Resource>() | Allow us to update a resource |
*Note that the resource is in the plural form.
What makes an API “good”?
Well, before we explore the different aspects that tend to make APIs “good”, let’s establish two simple reasons about what is the purpose of building an API. Overall, we can say those reasons are:
- We have some functionality that our users want.
- Those users want to use this functionality programmatically.
What are the desirable qualities of an API?
- Operational: it must do the thing the users actually want.
- Expressive: the API should be designed with a clear and straightforward way to do its work.
- Simple: expose the functionality the users want in the most straightforward way possible.
- Predictable: APIs that rely on repeated, predictable patterns (e.g. naming fields consistently) are easier and faster to learn.
Conclusion
To summarize, APIs are very useful and it’s important to learn how to design them. In future posts, we’ll explore some design patterns we can use to improve our APIs.