API’s are all over the place, but what are they actually? How do you create one? What are the best practices?
I’ll try to shed some light on these things over the next couple of months with this series on API’s. First off, let’s get the basics out of the way.
6 Alternatives to the Yahoo Finance API | Data Driven Investor
The Yahoo Finance API has long been a reliable tool for many of the data-driven investors. Many have relied on their…
Simply said, an API is an interface between a client and a server. The client sends requests for data to a server. Behind the scenes, the server fetches the requested information and responds.
The data can come from all sorts of places. It could be a database, a file or even another API.
So an API is what allows a client to interact with a server. The client can be anything. An android app, a website, a desktop application or a command-line program.
This is one of the reasons why API’s are so useful. When you implement the API you have to specify the contract (the structure of the responses and the requests), and as long as you adhere to this contract, it doesn’t matter who is going to use your API.
Which means you might have a web UI that interacts with the API, but nothing is stopping you from implementing an app later. Your backend won’t have to change at all.
Another powerful aspect of API’s is the fact that the client doesn’t care about the implementation of the server. The contract is king. How the server gathers and stores the data specified by the contract is entirely up to the implementers of the backend.
Making it more concrete
Let’s take a concrete example of the classic to-do list. Say we want to build an API for a to-do list service. Which means we need to specify the contract.
First, we need to tell the client how to query the API for a specific resource. Here a resource is a representation of specific data. In our case, a to-do list could be a resource.
The request could look like this:
GET specifies what kind of HTTP request to send. More on this later. The
/todolist specifies the resource we want data for.
Then we need to specify what you should expect to get as a response, which could look like this:
So as a programmer who wants to query the API, you know exactly what to expect when you send a GET request to
This is just scratching the surface though and over the next posts, I’ll be diving into what a REST API is and how to design one. We will also look at authentication, authorization, and pagination. Along the way, we will build our to-do list API as we explore these topics. As a bonus, I’ll also be looking into GraphQL and tips and tricks for Postman.
Thank you for reading, see you next time!
Next post → API 101: Designing kick-ass REST APIs