What Developers Should Know About APIs Before Building and Using Them – The New Stack

Marco Palladino

Marco Palladino is a San Francisco-based inventor, software developer, and internet entrepreneur. As CTO and co-founder of Kong, he is the co-author of Kong, responsible for designing and delivering the company’s products, while providing thought technical leadership around APIs and microservices within of Kong and the external software community. Prior to Kong, Marco co-founded Mashape in 2010, which became the largest API marketplace and was acquired by RapidAPI in 2017.

Application programming interfaces – widely known as APIs – have been around for decades to help companies transform into successful digital powerhouses.

In fact, in 2002, Amazon founder Jeff Bezos published a API Mandate forcing its developers to use service interfaces and share code. This tenure sparked my journey as a co-founder of tech startups to unlock the potential of APIs for developers. I’ve spent the past 13 years building foundational infrastructure and open source software that helps others build businesses, new applications, and increase efficiency using APIs.

The API economy is booming these days, and no one is questioning their potential, like when I founded my first company, an API marketplace called Mashape in 2009. The pandemic accelerated the shift to digital apps and services like never before, and there’s no turning back. In fact, just looking at the retail sector, e-commerce will double from 2017 levels to reach $563.4 million by 2025, proving that organizations will continue to claim to be API-centric companies.

As a software architect, application developer, or team leader, before you can develop a successful API strategy, it is essential to understand what APIs are and why they are essential for your business. I will address this below.

What are APIs?

An API is software that allows a computer program to communicate with another program to exchange data or consume some type of service. These programs can run on the same computer or on different computer networks thousands of miles apart.

An API connects a calling application (the client) and a called application (the service). The “service” can be a web server, a database server, middleware or even a monolithic application written in COBOL. As far as the client is concerned, they just need to know how to communicate with the API (endpoint URI, protocol, required parameters, etc.) without worrying about the underlying implementation of the service.

The API is the program logic to authenticate, validate, verify, and understand user input. Then it must process the request and respond to the client.

The client starts by sending a request – a request to the API endpoint.

Once the API authenticates the identity of the client, it validates the request message and performs further processing. Then the API passes the request to the service (which is sometimes referred to as the “backend” or “backend application”).

The service performs its operation based on the request, likely retrieving some of the requested data. It then returns a response message to the API, which includes the status of the operation (success or failure) and the requested data.

The API takes this message and sends it back to the client.

Figure: A simple API request-response scenario (image courtesy of Kong)

Figure: A simple API request-response scenario (image courtesy of Kong)

As you can see, it looks like a typical client-server application or human-computer interaction.

Common API Features

Regardless of how they are created or consumed, all APIs have standard functionality.

Defined interface

An API will have a defined interface. At a minimum, an interface includes the following elements:

  • Location of the API on the network.
  • What actions the API can perform.
  • What request and response message formats the client should provide to the API for these actions.
  • Security requirements for communicating with the API.

The client can only interact with the API through this interface. Typically, these details are laid out to a standard specification, such as WSDLName, RAML Where AEO.

Message format

For the client and the API to understand each other, they must agree on the format of the request and response messages. The API provider specifies this format as part of the interface. For example, the format may require that request messages adhere to a specific data format (such as JSON or XML) and use a predefined data structure. Similarly, the response will also have a predefined format and structure.


Finally, each API has a specific URL for the client and API to use to communicate. The URL includes the network protocol (for example, HTTP or HTTPS), hostname, and resource path (for example, /v2/myservice).


The implementation under an API is encapsulated, which means that developers using an API do not need to know its inner workings. A developer does not know if this API calls other APIs behind the scenes, or what data this API uses internally, or how the program logic of the API processes the data. The API is a black box and everything the API consumer knows about the API is in the documented API contract (interface, message format, protocol).

Linguistic independence

Since APIs are black boxes, developers can implement the API in any language without affecting the consumer’s ability to invoke the API. For example, if your client application is Java-based, it can still call an API written in .NET or Python.

Security checks

Finally, well-written APIs will have built-in security checks. For example, to defend against Distributed Denial of Service (DDoS) attacks, most publicly available APIs will have protections such as web application firewalls or API gateways. APIs may also require Secure Socket Layer (SSL) or Transport Layer Security (TLS) to encrypt data in transit. APIs can also implement input validation or require authentication (username/password or API key) for access.

Why use APIs?

Although all APIs have common core elements, their uses can vary widely. Some organizations develop internal APIs that are only accessible within a company’s network. Other organizations create partner APIs for use by partner companies. Some companies create public APIs for open or commercial use to provide access to their data.

Reduced time to market

One of the obvious benefits of using the API is the reduction in time and effort spent on software development. Developers can use the services and data already available, building new functionality on top of it. Increasing the speed of development helps companies stay competitive and reduce time to market.

There are no language barriers when it comes to writing or using APIs. Anyone can develop APIs in any language or framework. Likewise, the client application can be written in any language, independently of the language used for the implementation of the API.

Take advantage of new technologies

Companies can use APIs to take advantage of new technologies. For example, an organization can replace its legacy monolith application with a microservices-based distributed architecture. Suppose the backend functionality is exposed as an API. In this case, the implementation team can modify the backend architecture to stay true to the interface contract.

Discharge of responsibilities to third-party providers

Web application developers can completely offload user authentication using APIs from third-party vendors like Google or Facebook. These developers no longer have to worry about registrations or saving passwords.

Another example of API reuse is in e-commerce applications that enable payments with PayPal. The user authorizes the e-commerce application to debit their PayPal account. Once approved, the app calls the appropriate PayPal API to initiate a payment request. PayPal takes care of the rest of the transaction, including managing the balance and transferring the payment.

Integration into the commercial strategy

Companies also publish their APIs to increase brand awareness and monetization. For example, each time a payment is processed through PayPal’s APIs, PayPal retains a transaction fee (similar to banks). Some companies allow limited access to their APIs for free and full access with a paid subscription.

Popular API use cases

The following are a API in a few ways are used daily:

Cloud services

When we use cloud services (such as AWS, Azure, GCP, or DigitalOcean), we don’t realize that these are just large groups of REST APIs. These APIs help us access the service provider’s backend infrastructure and applications.

Cloud APIs are called whenever you start or stop a VM, save data to an S3 bucket, or invoke a Lambda function. Whether you’re using a web interface, working on the command line, or using an SDK, you send requests to an API provided by the cloud provider.

Mobile apps

Two major operating systems (OS) dominate the mobile device market. Each operating system has made its APIs publicly available through software development kits (SDKs). For Apple products, the developer documentation is the first stop for iOS developers. Similarly, Android has its developer page.


Platforms like Zapier or IFTTT allow you to create automated workflows between multiple internet-connected services, apps, and devices. Behind the scenes, these platforms use the APIs of the target systems to create the workflows.


APIs have been around for decades, but companies are only unleashing their true potential. APIs have proven to be essential for speeding up development cycles, introducing innovative new features to applications, and ultimately helping companies achieve their goals.

Feature Image by Thorsten Frenzel from Pixabay

Comments are closed.