Image for What is an API? A practical guide with examples

28 Jul 2020

What is an API? A practical guide with examples

APIs have become commonplace, so much so that even those who are not part of the software development community have probably heard of them and likely use them on a daily basis, many times without even knowing. In this article, we'll run through the basics of APIs including the difference between REST (Representational State Transfer) and SOAP (Simple Object Access Protocol), as well as provide some real-world examples. 

So what is an API and how does it work?

An API (Application Programming Interface) allows applications to access the features or data of other applications, operating systems, or services. Another way of saying it is that an API allows multiple pieces of software to talk to each other and defines how they interact.

Let’s look at a common example of how people interact with APIs on the internet. 

With each website hosted on a server, the internet can be described as a massive network of connected servers.  

Each time you click on a link or type a URL into a browser, a request is sent from your browser to the server the website is hosted on, the server then sends a response containing HTML, CSS, XML, JSON, media files, and other related content to your browser, which it then interprets to display the page.   In the diagram below the client is your browser and the server belongs to the website you're visiting, the API is what allows both the server and browser to interact. 

It's the mechanism by which they send and receive responses/requests. 

Example of API diagram

What are the different types of APIs and how are they used? 

API security

On an ownership level. 

Open APIs are publicly available for all developers to access without restrictions. 

Partner APIs are similar to open APIs on a technical level but do have restrictions in terms of who can access them and how they’re accessed. Partner APIs are often monetized. An example of a partner API would be a payment processing platform that allows you to process payments on your eCommerce site through their API and charges you a percentage of the transactions. Generally, these APIs are accessible through an API developer portal and are accessed by following a specific validation workflow. 

Internal or Private APIs are not accessible by external users. They work as an interface that grants access to parts of an organization’s backend data and application functionality. These are used by organizations to help speed up the app development process. 

The interface can be used by in-house developers and contractors to improve its products or services. Private APIs help reduce the time and resources needed to integrate IT systems and build customer-facing apps.

Popular types of web service APIs:

Web service APIs are applications that use URLs to provide services.  In a Web service, technologies like HTTP are used for transferring machine-readable file formats.

REST (Representational State Transfer)

The term was introduced and defined in 2000 by Roy Fielding in his doctoral dissertation. For an API to be considered RESTful it must follow six guiding principles.   

Client-Server—the system must be made up of clients and servers. The server takes care of the back-end and the client handles the front-end.

Stateless—the communication between the client and server must be stateless. Meaning all the information about the client’s session is kept on the client-side. Each request must contain all the required information to perform the request seeing as no browser cookies or session variables are stored to provide further context.    

Uniform Interface— describes the interface between clients and servers. The uniform interface constraint simplifies and decouples the architecture, enabling each part to evolve independently. In order to get a consistent interface, multiple architectural constraints are needed to guide the behavior of components.

Cache—responses must be defined as either cacheable or non-cacheable. The reasoning behind marking a response as non-cacheable is to prevent clients from providing old data in response to future requests. Caching responses will eliminate some client-server interactions, improving scalability and performance. 

Layered—The API should support a layered architecture, with each layer contributing to a transparent hierarchy. Each layer should be loosely coupled and allow for encapsulation. 

SOAP (Simple Object Access Protocol) 

SOAP is the successor to XML RPC and was originally designed for Microsoft back in 1998.  SOAP was the first to standardize the way applications use network connections to manage services. 

Despite the S in SOAP standing for simple SOAP is considered more complex than REST due to the level of security and the way messages are sent. 

While REST is easier to use, leading to it’s increasing popularity,  it isn’t always the right choice. 

SOAP offers comprehensive security and is ACID (Atomicity, Consistency, Isolation, Durability) compliant making it the preferred solution for enterprise applications dealing with banking transactions. 

Another way of creating efficient APIs 

Composite APIs allow developers to access multiple endpoints in a single call, which is useful when you need information from several services to perform a single task. For example, completing an order through a payment API might require access to multiple endpoints like “accept payment,” “send an invoice,” etc.

couple using shopping cart API

Reasons for the growing popularity of APIs 

One reason APIs are so widely used is the fact that they’re a reliable means of adding functionality to an application without needing to write all the code yourself. An example would be when you embed a map on your website showing your store’s physical location. You don’t need to know anything about how Google Maps’ code works. All you need to know is how to request the information through Google Maps API, making the process of showing a map on your website easy and vastly more efficient.    

APIs also allow developers to access data from other applications. For example, if you want to display the number of likes your page has on Facebook, you can pull the data from using Facebook’s Graph API.  

In conclusion, APIs are the lifeblood of the digital economy fueling our need for rapid innovation and continuous technological advancement. 

Enjoyed reading it? Spread the word

Subscribe to the
Blue Coding Weekly Rundown

Get helpful tips on remote jobs, our latest job openings, and more!