What Devs Must Know About APIs before Designing and Using Them – InApps 2022

Application programming interfaces — widely known as APIs — have been around for decades helping companies transform to successful digital powerhouses.

In fact, in 2002, Amazon founder Jeff Bezos issued an API mandate requiring his developers to use service interfaces and share code. This mandate sparked my journey co-founding tech startups to unlock the potential of APIs for developers. I’ve spent the past 13 years creating core infrastructure and open source software that helps others build businesses, new applications and drive greater efficiency using APIs.

The API economy is in full force these days, and no one questions the potential of them, 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 looking back. In fact, just looking at the retail industry, ecommerce will double from 2017 levels to $563.4 million by 2025 proving that organizations will continue to clamor to be API-first businesses.

As a software architect, application developer or team leader, before you can develop a successful API strategy, it’s vital to understand what APIs are and why they are critical for your enterprise. I will tackle 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 might run on the same computer or different computer networks separated by thousands of miles.

An API connects a calling application (the client) and a called application (the service). The “service” could be a web server, a database server, a piece of middleware or even a monolithic application written in COBOL. As far as the client is concerned, it only needs to know how to communicate with the API (endpoint URI, protocol, required parameters, etc.) without concern for the service’s underlying implementation.

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

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

Once the API authenticates the client’s identity, it validates the request message and performs additional processing. Then, the API passes the request to the service (which is sometimes called the “backend” or “backend application”).

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

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

Figure: A Simple API Request-Response Scenario (Image provided by Kong)

As you can see, this is similar to a typical client-server application or human-computer interaction.

Common API Features

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

Defined Interface

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

• Where the API is on the network.
• What actions the API can perform.
• What request and response message formats the client needs to provide to the API for those actions.
• Security requirements to communicate with the API.

The client can only interact with the API via this interface. Typically, these details are laid out according to a standard specification, such as WSDL, RAML or OAS.

Message Format

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

URL

Finally, every API has a specific URL to be used by the client and the API to communicate. The URL includes the network protocol (e.g., HTTP or HTTPS), the hostname and the resource path (e.g., /v2/myservice).

Encapsulation

The implementation underneath an API is encapsulated, meaning developers consuming an API don’t need to know its inner workings. A developer doesn’t know if that API is calling other APIs behind the scenes, or what data that API is using internally, or how the API’s program logic processes the data. The API is a black box and all that the API consumer knows about the API is in the documented API contract (interface, message format, protocol).

Language Independence

Because 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 consumer 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 like web application firewalls or API gateways. APIs may also require Secure Socket Layer (SSL) or Transport Layer Security (TLS) to encrypt the data in transit. APIs may also implement input validation or require authentication (username/password or API key) for access.

Why Use APIs?

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

Reducing Time to Market

One clear benefit of API usage is reduced time and effort in software development. Developers can use services and data already available, building new features on top. Increasing development velocity helps companies to stay competitive and decrease 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. Similarly, the client application can be written in any language, independent of the language used for implementing the API.

Leveraging New Technology

Companies can use APIs to take advantage of newer technologies. For example, an organization may replace its legacy, monolith application with a distributed, microservice-based architecture. Suppose the backend functionalities are exposed as APIs. In that case, the implementation team can change the backend architecture to remain faithful to the interface contract.

Offloading Responsibilities to Third-Party Providers

Web application developers can completely offload user authentication by using APIs from third-party providers like Google or Facebook. Those developers no longer need to worry about sign-ups or saving passwords.

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

Incorporating into the Business Strategy

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

Popular API Use Cases

The following are a few ways APIs are used every day:

Cloud Services

When we use cloud services (such as AWS, Azure, GCP or DigitalOcean), little do we realize that these are nothing but extensive groups of REST APIs. These APIs help us to access the service provider’s backend infrastructure and applications.

Cloud APIs are invoked every time you spin up or down a virtual machine, save data in an S3 bucket or call a Lambda function. Whether you are using a web interface, working in the command line or using an SDK, you send requests to an API provided by the cloud vendor.

Mobile Applications

Two major operating systems (OS) dominate the mobile device market. Each OS 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.

Automation

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

Conclusion

APIs have been around for decades, but businesses are only just now unlocking their true potential. APIs have proven vital in accelerating developer cycles, introducing new and innovative features to applications and ultimately helping businesses achieve their goals.

Feature image by Thorsten Frenzel from Pixabay