What is an API?

API is a buzzword in the tech industry. What does an API actually do though? This article will help you to familiarize yourself with what an API is and how it is used.

Let’s get started

API stands for Application Programming Interface. In a nutshell, it is what allows web applications to communicate with each other. Let’s look at an example of how we use APIs in our daily lives. Consider one of the many popular food delivery apps out there. When you place your order, that order is being communicated to the restaurant with an API. The credit card information that you submitted to pay for the order is submitted to a service like PayPal, with an API as well.

As you can imagine, we use APIs a lot in our daily lives. Basically anytime we make a request on one web application that needs to be sent to another web application, there is likely an API that is doing the work behind the scenes.

The main API categories are:

Operating systems APIs
Remote APIs
Database APIs
Web APIs

To keep things simple though, let’s just focus on Web APIs for now.

Web API

A web API is a a connection point that has been programmed into an application. This connection point can then be used to send requests to other web applications. These connection points for different applications communicate with each other in a request-response style.

Source

API Specifications

Hopefully that explanation helps to simplify things a bit, but as you can imagine there is a bit more complexity involved. This is where API specifications come into play. Let’s think about if for second. There are lots of different programming languages that one can use to make a web application. Also there are many different web browsers that one can use to browse the internet. Don’t forget, there are also a couple different OSs on the market these days. These factors along with others have to be taken into consideration. This is why API specifications were created. They are basically a set of rules that APIs have to follow to allow seamless communication regardless of the different variables that might be encountered on the internet.

Now the goal of this article is to keep things simple, so let’s just take a look at the two most prevalent API specifications that are being used today. Two of the most widely-used web API specifications in use today are: SOAP and REST. The main difference between these two, is that SOAP is a communication protocol and REST is a software architectural style. Let’s take a more detailed look at SOAP and REST.

SOAP

Simple Object Access Protocol (SOAP) is a communication protocol for exchanging data in the form of XML over the internet.

These are the components of a typical SOAP message:

Envelope – indicates that the start and end of the message
Header – contains attributes that can be used to process the message. The Header is optional.
Body – contains the XML data. The Body is required.

<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
  <env:Header/>
  <env:Body>
    <v2:performQuickScreenResponse xmlns:v2="http://schmas.robot-lending.com/services/V2">
      <v2:quickLoanParams>
        <java:code xmlns:java="http://schemas.robot-lending.com/service/QS/java">000</java:code>
        <java:accountNumber xmlns:java="http://schemas.robot-lending.com/service/QS/java">987193847087</java:accountNumber>
        <java:details xmlns:java="http://schemas.robot-lending.com/service/QS/java">Pre-approved</java:details>
        <java:amount xmlns:java="http://schemas.robot-lending.com/service/QS/java">25000</java:amount>
      </v2:quickLoanParams>
    </v2:performQuickScreenResponse>
  </env:Body>
</env:Envelope>

REST

Representational State Transfer (REST) is a software architectural style that communicates with HTTP or other transfer protocols that use standard Uniform Resource Identifier (URI). Typically the messages are sent as JSON and the content is often represented as objects following the concepts of Object-oriented programming.

Here is an example of what a REST API that is used to sign into a web application might look like:

POST /api/1.0/auth/signin HTTP/1.1
HOST: my-server
Content-Type:text/xml

{
  "credentials": {
    "name": "administrator",
    "password": "passw0rd",
    "site": {
      "contentURI": ""
    }
  }
}

These are the characteristics of a typical RESTful service:

Client-server based architecture – In this computing model, the server hosts, delivers, and manages most of the resources that are consumed by the client.
Stateless – This is the most important characteristic for a REST API. The server does not store any state about the client session on the server side. This is what the ST in REST stands for: State Transfer. This characteristic allows tremendous scaling because it reduces the amount of space that is being taken up on the server.
Cacheable – The ability to be cached is a requirement for a REST API. Content needs to be cached and then delivered as a response to ensure scalablity.
Multiple layered system – A REST API needs to be available from multiple servers. These servers are able to make requests among one another. The REST API on a scaled application should be able to passed between the servers and then supply a response to the client. Designing multi layered systems like this allows the web application to be loosely coupled and is ideal for REST APIs.
Representation of resources – A REST API uses a URI to map out the data. A REST API is able to make specific requests for the data format that it wants as a response.
Implementational freedom – REST is a flexible API and can be used in many different ways for many different things.

SOAP vs REST

For the needs of a typical web application, SOAP can often be overkill. REST is a more simple solution that is often all that is needed when a web application needs an API. However, there are some times when an API needs to be a bit more complex to get the job done. For instance, maybe the API needs to be capable of doing many things or maybe it needs to be automated. Choose a SOAP API for a scenario like that. However, if the task is relatively simple, then use a REST API. A REST API requires less processing and uses less bandwidth.

Choose SOAP if the task is big and complex. Choose REST if the task is simple and small.