API for Dummies: Learning API Basics

Have you ever wondered how different applications or websites can interact with each other and exchange information? Well, that's the magic of API. APIs, or Application Programming Interfaces, are a set of rules and protocols that allow different programs to interact with each other and share data or functionality. For example, when you use a weather app on your phone, it likely uses an API to fetch current weather data from a service. Or when you log into a website using your Google account, it also uses an API to access your account information from Google. APIs are everywhere around us, and they greatly simplify software development.

Why Are APIs Important?

You've just learned that an API is a set of rules and protocols that help different programs or even different parts of software communicate with each other. This might lead you to wonder why APIs are important or necessary at all.

It turns out that APIs are an essential part of what allows other developers to use your applications. Let's try to understand this with an example. You've probably seen various websites that have a "Sign in with Facebook" or "Sign in with Google" option.

These buttons use the OAuth protocol, which defines how websites/applications can obtain user data from Facebook and Google for a specific user after the user grants them access. Facebook and Google have created an API that implements the OAuth protocol. Third-party sites don't need to know how Facebook and Google handle authentication. They just need to know how to request user authentication from Facebook or Google on their behalf and how Facebook and Google can inform them of successful authentication. Without a proper API on these platforms, implementing social login functionality in apps would be very difficult.

Countless similar examples exist. Look at your computer. You can plug any mouse or keyboard into your computer, and it just works. This is possible thanks to the power of well-defined APIs. There is an agreed-upon protocol and communication method that all mice and keyboards must adhere to if they want to interact with the operating system. Thanks to this "API," new manufacturers can create new peripheral devices that are compatible with almost all common operating systems "out of the box."

Different Types of APIs

As you can infer from this incomplete description, there are countless APIs, and new ones emerge every day. Let's discuss a few important types of APIs and how they work.

What Is a REST API?

If you're building an application that uses data from third-party online services, you've likely encountered REST (Representational State Transfer) APIs. This is the most common way to implement APIs on the web. A REST API is based on the HTTP protocol and uses HTTP requests for POST (create), PUT (update), GET (read), and DELETE data. Such APIs are often exposed via a simple URL, such as https://example.com/api/users, and applications can interact with them by making HTTP requests to that URL/endpoint.

This architectural pattern for creating APIs was defined by Dr. Roy Fielding in his 2000 doctoral dissertation. He outlined 6 characteristics that an API must meet to be considered a REST API.

REST APIs typically interact with data in JSON format. No specification requires request/response data to be in JSON, but it has become a convention because JSON can be easily parsed in almost any language.

An example of a REST API is the Free Dictionary API. You can use this API by requesting https://api.dictionaryapi.dev/api/v2/entries/en/<word>, replacing <word> with any word you want to look up. A similar response you would get if you tried to look up the word "hello":

[
{
"word": "hello",
"phonetic": "həˈləʊ",
"phonetics": [
{
"text": "həˈləʊ",
"audio": "//ssl.gstatic.com/dictionary/static/sounds/20200429/hello--_gb_1.mp3"
},
{
"text": "hɛˈləʊ"
}
],
"origin": "early 19th century: variant of earlier hollo ; related to holla.",
"meanings": [
{
"partOfSpeech": "exclamation",
"definitions": [
{
"definition": "used as a greeting or to begin a phone conversation.",
"example": "hello there, Katie!",
"synonyms": [],
"antonyms": []
}
]
},
{
"partOfSpeech": "noun",
"definitions": [
{
"definition": "an utterance of ‘hello’; a greeting.",
"example": "she was getting polite nods and hellos from people",
"synonyms": [],
"antonyms": []
}
]
},
{
"partOfSpeech": "verb",
"definitions": [
{
"definition": "say or shout ‘hello’.",
"example": "I pressed the phone button and helloed",
"synonyms": [],
"antonyms": []
}
]
}
]
}
]

What Is a SOAP API?

SOAP API is another type of web interface. It uses a different protocol called SOAP (Simple Object Access Protocol) to transmit and receive data. SOAP is an XML-based protocol, meaning it uses a specific format for messages exchanged between the client and server.

SOAP APIs are typically used for more complex enterprise-level applications and require more careful setup and configuration than REST APIs. They can be somewhat more challenging to work with than REST because messages are transmitted in XML format, which is more difficult to parse and understand.

Here is an example of what a SOAP request might look like for a coupon API:

POST /Coupons HTTP/1.0
Host: www.coupons.org
Content-Type: text/xml; charset = utf-8
Content-Length: xxx

<?xml version = "1.0"?
<SOAP-ENV:Envelope
xmlns:SOAP-ENV = "http://www.w3.org/2001/12/soap-envelope"
SOAP-ENV:encodingStyle = "http://www.w3.org/2001/12/soap-encoding">

<SOAP-ENV:Body xmlns:m = "http://www.xyz.org/quotations">
<m:GetCoupon>
<m:CompanyName>Name</m:CompanyName>
</m:GetCoupon>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

And here is what the corresponding response might look like:

HTTP/1.0 200 OK
Content-Type: text/xml; charset = utf-8
Content-Length: xxx

<?xml version = "1.0"?
<SOAP-ENV:Envelope
xmlns:SOAP-ENV = "http://www.w3.org/2001/12/soap-envelope"
SOAP-ENV:encodingStyle = "http://www.w3.org/2001/12/soap-encoding">

<SOAP-ENV:Body xmlns:m = "http://www.xyz.org/quotation">
<m:GetCouponResponse>
<m:Coupon>Here is the offer</m:Coupon>
</m:GetCouponResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

What Is an Operating System API?

Just as SOAP and REST APIs allow two applications to communicate, operating system APIs enable interaction between a process and hardware.

For example, suppose you are writing a program that needs to access a file on your computer's hard drive. Instead of writing code that directly interacts with the hard drive, you can use the operating system API to perform file operations. This way, you don't have to worry about the details of how the hard drive works and can focus on your program's logic.

These operating system APIs are typically implemented using system calls. An example is the open() function from the C standard library. It uses the lower-level system call open and allows you to open a file without worrying about how to access a specific sector on the hard drive where that file might be located.

What Is a Database API?

A database API allows you to access a database and the information within it without knowing the specifics of how it works. This is how you can access and manipulate the same database from different programming languages, such as Python and Go. The database is not re-implemented in all these languages; instead, it provides an API with instructions on how to interact with it. This API is then used to create libraries and packages in different programming languages for that database.

A database API typically provides all the operations you can perform on a database. These include adding, deleting, updating, and reading database records. There are different types of well-known database APIs, such as ODBC, JDBC, ADO.NET, and others. Most are tailored to a specific programming language or a particular database management system.

What Is API Integration?

API integration means connecting two or more applications using their APIs. When you see web applications advertising integration with other applications/websites, it means they use API integration. An example is receiving a message in Slack when a new issue is created in Jira. Jira integrates with the Slack API, and Slack creates a new message every time Jira receives a new issue. Additionally, Jira allows you to create new issues directly from Slack.

APIs vs. Website Interfaces

You can use the web interfaces of various applications to access underlying data. For example, you can use Google Translate's web interface to translate text from one language to another. However, there are a few caveats when automating such interactions.

Website interfaces tend to change almost without notice. If you integrate with an application's website interface using web scraping, your integration may break if the site interface changes even slightly. In contrast, APIs are typically versioned, and a new API version does not eliminate the old API.

Furthermore, APIs typically provide data in an easier-to-process format, most often JSON. This saves you the extra effort of converting data into a usable format.

Unless you have a strong reason to use a website interface for integration, it's better to rely on official APIs, as they are more reliable and designed precisely for this purpose.

How Do APIs Work?

We'll focus on REST APIs since they are the most common type you'll likely encounter. It's important to note that REST is an architecture, not a protocol or standard. Developers can implement a REST API in various ways. The actual request-response cycle in a REST API will differ depending on the language and web framework you use to implement it. However, the general cycle will look something like this:

Request: The client sends a request to the server using an HTTP method such as GET, POST, PUT, DELETE, etc. The request contains information about what the client wants to do, e.g., get data, create a new resource, or update an existing one.
Routing: The server's REST API framework receives the request and maps it to a specific endpoint. An endpoint is a URL that corresponds to a particular resource or action on the server.
Processing: The server performs the requested action and generates a response. The response contains information about the operation's results, such as data, status codes, and headers.
Response: The server sends the response back to the client. The response contains information about the operation's outcome, as well as any data the client requested.
Processing: The client receives the response and processes it. Depending on the nature of the request and response, the client may take additional actions, such as displaying the data to the user or making another request to the server.

Whenever you read the word "resource" when learning about REST, it refers to data on the server. If we look back at our earlier dictionary example, the dictionary contains many entries, and those entries are a resource. REST endpoints are typically resource-oriented, and one endpoint manipulates only one type of resource. Therefore, the URL for working with the "entries" resource explicitly contains the word "entries":

There are four main types of requests in a REST API. These types are based on existing HTTP verbs:

GET: Used to retrieve information from the server. A GET request should not change the server's state and is typically used to obtain a representation of a resource.
POST: Used to send information to the server. A POST request is typically used to create a new resource or update an existing one.
PUT: Used to update an existing resource. A PUT request should completely replace the current representation of the resource with the one specified in the request.
DELETE: Used to delete a resource. A DELETE request should remove the specified resource from the server.

In public APIs, the type of request possible for each resource is usually very clearly indicated.

Since REST works over the HTTP protocol, HTTP headers are also very important. Headers typically contain important information related to the request in the form of the following header entries:

Accept: Specifies the media types the client is willing to accept in the response. This is mainly JSON for REST requests.
Content-Type: Specifies the media type of the request body, if any. This header is typically used in POST and PUT requests when the client sends data to the server.
Authorization: Contains authentication information, such as a token or a username and password. This header is used to identify the client and determine if they have the necessary permissions to access or modify the requested resource.
Cache-Control: Specifies caching instructions for the response, such as whether the response can be cached and for how long. Caching is an integral part of the REST architecture.
If-Modified-Since: Specifies a date and time used by the server to determine if the client's cached copy of the resource is still valid. If the resource has not been modified since the specified date, the server may return a 304 Not Modified response instead of the full resource.

These header keys/values are not specific to REST; rather, REST leverages these existing HTTP headers to simplify its architecture.

Real-World Use of APIs

Many popular APIs are used by developers every day. One key example is the Google Maps Embed API. If you see Google Maps embedded in a website, developers are using this API in the background.

Public APIs like these are generally simple to use. First, you need to visit the developer documentation site for the relevant API. The documentation usually contains enough information to get you started with the API as quickly as possible. This is done so that developers don't spend too much time learning a new API.

To show how easy it is to use the Maps Embed API, you only need to include the following IFrame in the body tag of your website:

<iframe
width="600"
height="450"
style="border:0"
loading="lazy"
allowfullscreen
referrerpolicy="no-referrer-when-downgrade"
src="https://www.google.com/maps/embed/v1/place?key=API_KEY
&q=Space+Needle,Seattle+WA">
</iframe>

The IFrame will start working once you replace API_KEY with a valid API key from Google. You can request an API key by creating a developer account. This process is detailed on the API documentation site. This also illustrates how some public APIs use API keys to ensure unauthorized access is prevented.

Once the embed is working, you'll see a beautiful map of Seattle.

Other popular APIs include the Recaptcha API. It appears whenever you browse the internet and a site asks you to confirm you're human. That image might help you recall those amusing moments when it was particularly hard to prove you're not a robot.

A very good resource for finding public APIs is RapidAPI. Their site contains information about various free and paid APIs. Another similar resource is the page on GitHub.

Conclusion

In this article, you learned about APIs: what they are, where to find them, how to use them, and how different types of APIs differ from each other. This knowledge is hard to absorb without experimentation. You need to try out different APIs, read their documentation, and understand how they work.