In a nutshell, (Application Programming Interface) refers to how programs or services can request data from other services.
Twitter API Example
Twitter has a website where we can view tweets. By clicking on the links, we can go to addresses where different information is available, such as your feed, a page for a particular tweet, your profile, password reset, your advertising account, and so on:
- https://twitter.com/hexlet_io – a particular user's page
- https://twitter.com/hexlet_io/status/1613590336932122643?s=20 – a page for a particular tweet
These pages return HTML that presents the information as we see it, with all the design elements. Twitter's developers adapted the site for small screens, so it opens from any device with a browser. But besides the website, Twitter has a mobile application that displays the same data, but with a different, more convenient interface adapted for that specific phone.
The mobile app, unlike the website, is physically stored and runs directly on that specific phone. And the whole appearance is also defined inside the application. For such an application to work, you need clean data, but that data aren't on your phone, they're on Twitter's servers. How do you get them on your phone? Ordinary page addresses don't suit us, as they don't return the data we need but rather ready HTML pages.
It is where the API comes to the rescue. Twitter provides HTTP addresses where pure data, rather than specific web pages with ready-made appearances, are available. Data at these addresses are given in a structured format, most often JSON. One service packs the data into JSON format, then another service unpacks it from JSON and uses it to display the data in the app. Here you see an example of a user request:
# The address to which the list of specified users is returned
# In this case, one user is requested
https://api.twitter.com/2/users/by?usernames=hexletHQ
# As a reply, you get some JSON of the following structure:
{
"data": [
{
"created_at": "2013-12-14T04:35:55.000Z",
"id": "2244994945",
"name": "HexletHQ",
"description": "Hexlet - programming courses",
"pinned_tweet_id": "1464165859761573893",
"username": "hexlethq"
},
],
}
The task of this API is to provide convenient access to Twitter data. And this API is used both by Twitter in mobile applications and by third-party services that manage Twitter. For example, marketers use services that automatically publish tweets according to a schedule.
By the way, Twitter uses its own API, including widgets. We can embed it on any website to display a particular tweet or feed of tweets, like on Hexlet main. And, Twitter's site itself runs on the API. It loads JS code into the browser, which implements the logic of the output and goes to the server to get data (via the API).
Twitter has a site for developers with a detailed description of their API, addresses, parameters that can be transferred, and response formats. Similar descriptions are available for any service with a public API, services available for use on the Internet. Of course, a public API doesn't mean a free one. An API can be and often is paid.
HTTP API
The Twitter API is an example of an HTTP API; it works over the HTTP protocol. Browsers use it to load and display sites. HTTP is the most common and convenient way to make an API for public internet services. The whole Internet is flooded with it. It's well-supported by most programming languages. After all, it's a simple protocol that all web programmers know one way or another.
But not all HTTP APIs are the same. HTTP leaves a lot at the mercy of developers. So, HTTP APIs can differ drastically, for example, in their data format. The most popular formats are JSON and XML. They are very similar in appearance, but XML describes data rather than how the data are arranged and appear:
<!-- Just an example of an API from the Internet -->
<Contents>
<Key>europe/france/cannes.jpg</Key>
<LastModified>2010-02-17T22:11:12.487Z</LastModified>
<ETag>"53fc311c15eda0a031809982ccf92aac"</ETag>
<Size>5061631</Size>
<StorageClass>STANDARD</StorageClass>
</Contents>
There are other formats, but developers use them much less frequently. Generally, HTTP doesn't limit the format, so you can create and use your own.
Besides formatting, HTTP APIs differ in how their addresses are structured. For example, code-basics has a different address for each type of data:
- https://code-basics.com/api/languages.json – list of languages that have coureses
- https://code-basics.com/api/languages/12.json – course information
- https://code-basics.com/api/languages/12/lessons.json – list of language course lessons
This kind of API is often called a REST API. You can read more about it in another article. Sometimes, API addresses can look the same, but different request parameters are sent to it. This method has many variations, such as json-rpc, graphql and others:
# All requests go to only to this address
https://some-site.com/api/rpc
https://some-site.com/api/rpc?param=value
Finally, we have the WebSocket API, where communication goes both ways in real-time, as opposed to the examples above, and the client (the one using the API) has to request the data itself. Websocket is used to make real-time applications such as chat or games. In these applications, data exchanged on the server must be sent as quickly as possible to all interested clients.
Non HTTP API
APIs don't just have to be HTTP. Typically, these APIs are found within a service to facilitate components interacting. Each part behaves like a small service. These APIs can:
- Use another protocol, such as TCP
- Lean on other approaches, such as queue systems or threads (grpc, rabbitmq, kafka)
