APIs for Dummies: Everything You Need to Know

An API (Application Programming Interface) is a set of functions that allows applications to access data and interact with external software components, operating systems, or microservices. To simplify, an API delivers a user request to a system and sends the system’s response back to a user.

APIs are highly used because they can make things way easier and speed up the development process of other systems and applications. For example, if you are building your own software and wish to integrate face recognition or payment processing, it is best to use an API. You just have to connect your software with another one. These are provided with the API’s documentation, a manual for developers to help implement the desired functionalities.

Using an API, you don’t need to deal with any source code or even understand how it works. Sounds good, right? Cool, let’s take a look at just how APIs do that.

Think of an API as the “middleman” between your application and the server. You tell your app to do something for you; then the app will use an API to communicate with the web server, telling it what to do. This action is called a request. Afterward, the server will send a response to be delivered by the “middleman” to your app.

Let’s see a less abstract example. You walk into a restaurant, pick a table with a view and wait for the waiter to get your order. In this case, the waiter is your “middleman” because the cook cannot take your order directly, as he has other orders to prepare in the kitchen. You make a request to the waiter, the waiter sends said request to the kitchen, then gets a response, in this case, your order, and brings it to your table. Enjoy your food!

Even the API is an abstraction of the web server, as the application doesn’t know what is going on in the “kitchen,” just what the final result will be. The end-user knows that if he orders a cake from the menu, he will get a cake. There are many types of APIs, depending on what they’re built to do or their release policy. Let’s take a look at these differentiators.

APIs are handy. As we mentioned above, communication between various software and apps is essential in order to achieve a particular goal, so an API is designed based on what you want to accomplish. Let’s see a few examples:

• Database APIs make communication between an application and a database management system easier. For example, Firebase is a mobile web application platform owned by Google that lets developers simply sync and store data in real-time without having to manage servers or write server-side code.
• Operating systems APIs. Even operating systems have a fair number of APIs, for example, Windows API or the Linux Kernel User-Space API. You can also find the APIs provided by Apple for macOS and iOS and presented in their developer documentation.
• Remote APIs interact through a communications network. The most common communications network is the Internet, so APIs are usually designed based on web standards. But that doesn’t mean that all remote APIs are web APIs. Still, Web APIs are generally remote, typically use HTTP for request messages, and define the structure of response messages. These messages are preferred to be in XML or JSON format as it is easier for other apps to parse the information.
• The most commonly used APIs are Web APIs because they send requests from a web application and responses from servers using HTTP (Hypertext Transfer Protocol). Developers make use of such web APIs in their apps or sites, increasing their functionality and making them more practical for the user, like integrating a login method via Facebook or Google or adding a map using Google Map API.

Some APIs are built only for internal use. This is particularly common for large enterprises. Others are designed as products meant to integrate with whatever software customers use. These are the main categories:

Private APIs are mainly used inside one’s organization, integrating them in systems and apps used by their employees and improving the internal operation. Even if they appear open to the public, the interface remains available only for those within the organization, which has complete control over the API. It also reduces some costs for the organization.

Partner APIs can provide additional revenue streams as they are shared with one or more business partners. An agreement is made between said partner and the publisher. A partner API also adds value to the service and opens up a channel for up-selling.

Public APIs are available for any third-party developers. These types of APIs don’t need to have a close relationship between the user and the publisher, they can increase the revenue stream, help reach larger audiences and build traffic, and support many causes and a variety of business initiatives. Public APIs can be either:

• Open: These APIs can be used by somebody however they please, which means that there are no restrictive terms or conditions, you don’t need the punisher’s consent to use the API and you don’t have to pay for it. They provide public documentation for developers to access and can be utilized to test and create applications.
• Commercial: In order to use such APIs, you will have to pay a subscription fee. In order for users to test and review the product, publishers often offer a free trial so that the customer knows whether or not to purchase a subscription.

Of particular interest are SOAP APIs and REST APIs since these are very widespread. Let’s take a look at the concepts behind the acronyms:

SOAP or Simple Object Access Protocol APIs are web communication protocols and are used for exchanging information and structured data over HTTP/HTTPS. Unlike REST APIs, SOAP supports the XML data format only. Most web data exchange is realized over REST exchange, but that doesn’t mean that SOAP will have its downfall anytime soon, as it is highly standardized, more secure, and sometimes allows for automation.

XML or eXtensible Markup Language is a tool independent of software or hardware for storing and transporting data. It has a set of rules for structuring messages as both human and machine-readable records. As you may see below, its structure is similar to HTML, but the XML language has no predefined tags, so the author must define both tags and the document structure.

The Representational State Transfer is an architecture style created by Roy Fielding in 2000 for designing coupled applications over HTTP and is often used in API development. For a service to be referred to as RESTful, it mustn’t violate these constraints.

Developers prefer using REST as an alternative to SOAP because it doesn’t involve writing a lot of code to achieve simple tasksUnlike SOAP, which needs you to create the required XML structure every time. RESTful web service uses a different approach. It treats information as a resource represented by a unique URL. So if you want to request a certain resource, you will have to provide its URL using HTTP methods such as GET, POST, PUT, HEAD, DELETE, PATCH, and OPTIONS. You can find more about these methods here! Sometimes you might need to send additional data along with the URL in order to get what you need, like an access key.

Unlike SOAP, REST isn’t limited to using XML to provide the response. You can obtain the information in different formats like JSON, XML, CSV, plain text, and HTML, which are parsed easier based on the language you’re using for your application.

Here is a comparison between JSON and XML:

You’ll often hear developers talking about the functionalities of different APIs, but there’s another important, less discussed aspect: the documentation. Without the knowledge in it, an API might as well be a bunch of hieroglyphs.

An APIs documentation isn’t some videogame tutorial you can skip with nonchalance and learn its mechanics along the way. The documentation contains instructions on how to effectively use and integrate said API.

Even if an API is revolutionary for developers, poor documentation or lack of knowledge on how it works would make it useless.

Well-written documentation can help save support time and costs. Onboarding new users become easier and they won’t need technical support for using the API. A poorly written documentation can be rather frustrating for developers and the publishers’ support team.

Some documentation may provide a demo section or a playground where you can test things out and see live results. This helps developers visualize what the API does and have a better understanding.

I hope our APIs for Dummies helped you better understand how APIs work and just how important they are in the world of information technology.

The growing number of apps and software products, both corporate and for personal use, need communication and resource exchange methods. APIs satisfy that need and are key in helping the expansion of technology.

Check out this article on web scraping APIs to see a few examples of web APIs in action!