The term API stands for Application Programmable Interface. This term is frequently used in connection to programmers, the specific tasks an API can perform, or the data it can retrieve. Over the past ten years, the use of APIs has increased so that many of the most well-known web services today would not be viable without them. But what exactly is an API?

What are APIs

Let’s explain it with a real-life example. Let’s say you went to a mechanic to get your car repaired. You can ask him what’s wrong with your car, how the mechanic can fix it, and how much it costs. In this scenario, the mechanic protects you from all the intricate details in the background. For instance, the workers that do the job and all the tools. The mechanic is the interface between you and all the services that he provides. He gives you a means of communication while protecting you from all the complexity in the background. In this example, the mechanic can be seen as the API. Therefore you can consider the mechanics in the back fixing your car as the backend, the shop is the front end, and the mechanic you talk to is the API.

How do APIs work

APIs are all around us. If you have ever checked the weather on your phone or logged in to an application using google or Facebook or even used google maps, you have come across an API. Your phone’s weather app “talks” to this system via APIs to provide you with daily weather updates. In simple terms, a client application initiates an API call (also known as a request). This request is handled from an application to the web server using URI that includes a request verb, headers, and sometimes a request body. The server retrieves, interprets, puts to use, and sends the data back to your phone. The application then analyzes the data and displays the information you requested understandably. The API is the middleman between the two systems. It allows the application and the web server to talk to each other. However, APIs aren’t limited to the web. Every machine or system that anticipates interacting with other machines or systems can have an API. 

There are often a few essential pieces of information in most API requests:

• Type of request
• Authorization credentials

There exist multiple types of HTTP requests. Let’s dive into some of them.

1. GET: to Get data from a resource
2. PUT: to Update data at a resource
3. POST: to Create data at a resource
4. DELETE: to Delete data at a resource
5. PATCH: to Partially update data at a resource

Authorization credentials

Authorization limits a user or a service from performing certain activities. For example, you may authorize a person to view a specific document. However, they can not edit it since they are not authorized to do so. In terms of APIs and services, we always use Authorization instead of Authentication (which is a technique that prevents individuals from accessing sensitive data), and that is to ensure that client requests access data securely.

Type of APIs

It has been agreed that four types of APIs exist: 

• Open APIs

• Partner APIs

• Internal APIs

• Composite APIs

• Let’s have a close look into them:

Open APIs:

Also known as public APIs or external APIs, they are available to use by any developer. 
They provide the fewest constraints to developers and other users. They may be open or need registration and the usage of an API key. An API key is used to authenticate a user. Consequently, for open APIs to be so public, they have weak authentication and authorization protocols. Sometimes, a subscription may be required to get all the benefits of open APIs. The main benefit of making APIs public is the availability of open data sharing. This promotes any outside company or developer to integrate with the application that owns the API, increasing the value of both the third-party program and the API. 

Internal APIs:

Internal APIs (also called private APIs) are the opposite of open APIs and are intended to be obscure to outside users. They are utilized inside a business to exchange resources, and these APIs are only accessible to internal developers within the company. However, a lot of businesses make their internal APIs public at some point in time. Since these APIs are hidden, they are considered more secure and efficient.

Composite APIs:

Composite APIs are a combination of many APIs used when data from different applications is required. This type of API is very efficient since they send one single API call to multiple applications. But why don’t we use a public or an internal API and send multiple requests instead of one composite? Because the more API hits that you encounter, the slower your system will be and the less optimized it will become. We should mention that there exists an API called Batch API. At first glance, they may seem similar. A composite API satisfies a batch API’s demands, while the reverse is false. Batch APIs group API calls that aren’t necessarily related. The difference between batch APIs and composite APIs is that batch APIs can be gathered together and supplied in a single call, but no sequencing is involved.

Partner APIs:

Partner APIs are shared externally, similar to Open APIs, but they are available only among a targeted audience (have subscriptions/clients). Since it’s only limited to a group of authorized people, the security measures tend to be stronger than public APIs. This API is appropriate for businesses that wish to control who has access to their information. A good example would be Twitter and Pinterest requesting partners to submit a request outlining their intended API usage before granting them access.

APIs Architecture and Protocols

We know the client-server concept, and we know that they talk to each other with the help of web services. The guidelines for what data an API can share with clients and how it communicates the data make up the architecture of an API. REST and SOAP are the two most popular architectures. 

REST

Representational state transfer (REST) is a set of guidelines for scalable, lightweight, and easy-to-use APIs. But what are they? It’s a set of rules that is the common standard for building web API. An API that follows the REST standard is called a RESTful API. APIs are RESTful as long as they comply with the 6 guiding constraints of a RESTful system:

1. Client Server architecture: REST applications should have a client-server architecture. The client needs to connect to the server, which is done by issuing a request. The client needs to provide two things. (1) Endpoint: A client interacts with a resource by requesting the endpoint for the resource over HTTP. (2)Method: HTTP can have multiple request methods (as discussed previously), and select any of them.
2. Statelessness: No client information is stored on the server between requests. Each client-server interaction is distinct from all others.
3. Cacheability: Some client-server exchanges may not even be necessary due to caching.
4. Layered system: The client can’t have a direct connection to the server. A hardware or a software intermediary can exist between the two.
5. Uniform interface: To ensure compatibility between any client and server, all requests and answers must use HTTP as their communication protocol and follow a specified standard. A request uses HTTP verbs like POST and GET, while a response uses a HTTP status like 200 => OK 201=>Created 401=> Unauthorized 404=> Not Found.
6. Code on demand (Optional): Servers can increase a client’s capabilities by sending executable code.

SOAP

Stands for Simple Object Access Protocol. Any web service that complies with the SOAP web services specifications is a SOAP web Service. SOAP protocol says that all the exchange of data or messages between client and server has to be in a common format. In the case of SOAP, it has to be XML. The XML message has a structure of a SOAP message, and the SOAP message consists of envelopes, a Header, and a Body.

SOAP vs. REST

In contrast to SOAP, a protocol with precise specifications like XML messaging, REST is a set of rules that allows for flexible implementation. REST can use SOAP web services because it is a concept and can use any protocol like HTTP or SOAP. However, SOAP can not use REST because it is a protocol. Thus REST is easier and more widely used for its easy implementation and loosely set of rules.

Conclusion

So for the question SOAP vs. REST which one should you choose? The answer is: it depends. Each protocol has definite advantages and disadvantages. The programming language you choose, the context in which you use it, and your needs will determine whether you choose SOAP or REST. And always make sure you thoroughly test your APIs regardless of whether you choose SOAP or REST for your online service.