Application Programming Interface - What is an API and how does it work?

Application Programming Interfaces (APIs) help you integrate software programs and introduce new features to your product.

Organizations use APIs to integrate their apps and introduce new features and functionality to their products. There are many third-party API providers out there for every use case — learning about how APIs work and how to test them will help you choose the best APIs for your products.

What Is an Application Programming Interface (API)?

An Application Programming Interface (API) is a set of protocols and routines that helps two or more software applications to interact with each other and share data, functionality, and services.

You can use APIs to integrate internal applications so that data can flow from one app to another and finally to data repositories and then be used for business intelligence. For example, you need your marketing data to make it to your CRM, and for that to happen, you need to integrate the two systems with an API.

API integrations are also used to test new product functionality and features in a staging environment and make new features available to end users of your web or mobile app.

You can also use third-party APIs to gain access to pre-built features. For example, you can use APIs from the Google Maps Platform to add maps, routes, directions, and street view to your apps or Stream's chat API to introduce a chat feature to your apps. The CNN iReport Map is a good example of how that works. CNN uses the Google Maps API for its map as well as to mark locations from where contributors send the network stories.

How Does an API Work?

For a regular user of an app, APIs work in the background to carry user requests from the app to the server and bring back the server's response. The user taps a button and moves from screen to screen, gaining access to data and using features.

Here's how APIs work from a product team's perspective:

The product manager, working with developers, chooses an API provider (in the case of a third-party API).
The API provider gives them an API key and documentation.
A developer integrates the application with the API by following the API provider's instructions. They do this by understanding the API specifications, defining API endpoints and request methods, and using the API key.
The developer defines how the data will be parsed in the app and presented to the user.
The developer sets up a test/staging environment for the QA team.
The QA team tests different types of API requests based on the functionalities offered by the API provider.
If the testing goes well, the developers go live with the API.

If the API in question is an internal API, you can skip the first two steps, but everything else remains the same.

To dive deeper into how APIs work, let's look into the key API terms we mentioned in the process above.

What Is API Documentation?

API documentation is a detailed manual for developers that tells them how to set up the interface. Every third-party API provider offers documentation to its users. API documentation should include:

A detailed tutorial on setting up the API and making API calls (requests) - This will help developers easily use the API and take any guesswork out of the equation. They will go through the tutorial and have a frictionless experience setting up the API.
An explanation and examples of every request, parameter, and response - This will help developers understand the kind of requests they can make and the responses the API will likely deliver. Developers then use this information to make sure the user interface works seamlessly with the API and reduce the chances of errors.
Examples of error messages - Every API has a list of pre-defined error messages. A list of those messages, along with examples, will help developers plan for error mitigation.
Code samples - These make the developer's job easier, as they can simply copy and paste the code, make changes to it, and integrate the API with the product. Developers work with code throughout the day, so code samples will resonate with them more than any other elements of API documentation.

Consider Stream's API documentation. It gives the developers a ready-made client and framework library for all major programming languages, as well as frameworks such as Rails, Django, and Laravel. It provides an introduction to the basics, detailed examples of API tokens, an explanation of how the requests, parameters, and responses work, and information on naming conventions and best practices for using the Chat API. That way, any developer working with the API can get all the information they need in one place.

What Are API Specifications?

API specifications explain how the interface functions, what to expect from it, and how it behaves with other APIs.

API specifications explain the API's behavior and set expectations, whereas API documentation is a guide with step-by-step instructions for developers. API specifications are written for product managers and developers alike, whereas API documentation is specifically written for developers.

Some third-party API providers combine API specifications and documentation and provide all of that information in the same area.

Consider OpenAI's specifications from GitHub. These specs define an OpenAPI document, its format, structure-supported data types, and different implementations of schema. They also have a number of code samples. There are some elements of API documentation as well, but they are primarily written with the intention of helping people understand the capabilities of the service.

What Are API Endpoints?

APIs generally consist of three core components:

Client - The app or any software program that makes a request (or sends an API call)
Resource - The file or piece of information requested by the client
Server - The place where the file/information is located and where the server sends a response

An API endpoint is the exact location on a server where a requested resource exists. You access endpoints every time you make a request.

Let's say you want to retrieve a list of subscribers from a server. The API endpoint for such a request would look like this: https://api.example.com/v2/subscribers.

In this case:

https://api.example.com is the base URL of the API
/v2/ indicates the version of the API
/subscribers is the specific resource you want to access

Along with the endpoint, you have to mention an HTTP request that tells the server what to do with the requested resource. Standard HTTP requests include:

GET - To retrieve a resource without making changes to it
POST - To create a new resource
PUT - To update a resource
DELETE - To delete a resource

Endpoints accept these standard HTTP requests and return responses in JSON or XML. Let's go back to the earlier example; to retrieve a list of subscribers from example.com, your GET command would look something like this:

GET https://api.example.com/v2/subscribers

What Is an API Key?

An API key is a unique code assigned to each customer by third-party API providers. The code is used to identify and authenticate the app making the API call. API keys protect the API provider by blocking anonymous traffic and limiting the number of API calls.

When making a request to an API, the client application includes the API key as part of the request in the request header or query parameter to authenticate itself and gain access to the API's resources.

API keys are often used in combination with other authentication mechanisms, such as OAuth, to ensure API security and provide secure and granular access control to an API.

What Are API Tokens?

API tokens or access tokens are small snippets of code that are used to identify individual users or devices. These tokens have a header, a payload, and a signature.

Header - Lets the API know the token's format
Payload - Contains user identification information, such as a username and user permissions
Signature - Contains hashed data for user verification

Users working with APIs need to get device-specific API tokens. API tokens are issued by an authentication server to a client application or user after it has successfully authenticated and authorized the client to access a specific set of resources or actions. Once a token has been issued, each API call being made through a particular device will contain that token.

API tokens are different from API keys in that they can authenticate individual users and devices, whereas API keys authorize entire apps. For example, if an app uses Stream's Chat API, any user from that app can use the chat feature because the app they are using is authorized to access said feature. In contrast, API tokens allow more granular control where different token holders (users of an app) have different levels of access to data.

Different Types of APIs

We can classify API types based on their use cases as well as API protocols and architectures.

API Use Cases

The ways APIs are used in these instances have nothing to do with how the API is designed or how it works but everything to do with who has access to it.

Public APIs are available to everyone, but there may be a price tag and/or authentication involved. Examples include Google Maps and the Log in with Twitter, Sign in with Google, and Facebook Login APIs.
Open APIs are free and available to everyone without any type of authentication or authorization. All open APIs are public APIs, but not all public APIs are open. iControl SOAP is a good example of an open API.
Private APIs are available to only a select few people. Examples include APIs available to employees and partners of a company.
Partner APIs are only available to partners of a company.

Another way to classify these use cases is to see who developed the API, who is using it, and how it is being used:

Third-party APIs/External APIs are used by organizations that didn't develop them.
Internal APIs are developed by an organization and used within the organization's ecosystem.

Classification Based on API Protocols and Architectures

APIs are commonly classified into five different types based on protocols and architectures.

REST APIs

REST (Representational State Transfer) or RESTful APIs are scalable, flexible, secure, and more efficient as opposed to other types of APIs. REST APIs are the most commonly used API type because they are ideal for use with web and mobile apps. RESTful APIs adhere to the six REST architectural constraints:

The uniform interface constraint requires that the API has a consistent and standardized way of interacting with resources. The API should define a clear set of operations that can be performed on resources, and these operations should be the same for all resources. The uniform interface makes it easier to understand how to interact with the API and enables the separation of concerns between the client and server.
The client-server decoupling constraint requires that the client and server should be independent of each other and able to evolve separately. This means that the API should be designed in such a way that the client does not need to know about the server's internal workings, and the server does not need to know about the client's requirements. This makes it easier to maintain and scale both the client and server independently.
The stateless constraint requires that the API should not maintain any state information between requests. Each request from the client should contain all the information required by the server to process the request (and should not rely on information from the previous request). This makes it easier to scale the API since the server does not need to maintain any session state information.
The cacheability constraint means that the API should include caching information in its response headers to allow for efficient caching of responses by intermediaries such as web browsers, proxies, and CDNs. This can significantly improve the performance of the API.
The layered system architecture constraint requires that the API should be designed in a layered architecture, where each layer should only be aware of the layers immediately below it and above it. This enables intermediaries such as load balancers, caches, and gateways to be introduced between the client and server without affecting the overall architecture of the API.
The code on demand constraint is an optional constraint that allows the server to transfer executable code to the client on demand. This can be used to enhance the functionality of the client and reduce the amount of data that needs to be transferred between the client and server. However, this constraint is not commonly used in RESTful APIs, as it can make the API more complex and harder to maintain.

These APIs are not without their challenges, though. As RESTful APIs evolve and change, it can be challenging to maintain backward compatibility and versioning. This can result in versioning issues and require additional development effort to ensure compatibility with existing clients.

RPC APIs

RPC (Remote Procedure Call) APIs are the earliest form of APIs. They help execute a snippet of code on a server by sending a group of parameters and instructions to the server and receiving results.

RPC APIs work similarly to REST APIs in that they carry requests to a server and bring back responses, but they do not follow any of the constraints of the REST APIs. The communication between the client and server can happen over different protocols, such as HTTP, TCP/IP, or UDP. The specific protocol used depends on the requirements of the RPC API.

RPC APIs can be developed with the help of frameworks such as gRPC and Apache Thrift. These APIs are not as much in use anymore because REST APIs deliver better performance. RPC APIs create tight coupling between the client and server, and any changes to the API require updates to both the client and server. The coupling between the client and server causes errors and makes maintenance a hassle. In REST APIs, the client and server are decoupled, and developers can make changes to the API as needed without having to make changes to the server and the client.

SOAP APIs

SOAP (Simple Object Access Protocol) APIs use Web Services Description Language (WSDL) to define the structure of messages and a proprietary XML format to transfer data. The requests and responses are sent using the HTTP or HTTPS protocols. These APIs are reliable and secure and are still used in enterprise applications to a certain extent.

API calls with SOAP APIs are stateful as opposed to REST APIs. In other words, the server stores information about the client, and the response to new requests may depend on the state of the previous requests. That can make SOAP APIs harder to scale. SOAP APIs can also be slower than other APIs due to the additional overhead introduced by the SOAP protocol and XML message format, especially when handling large volumes of data.

GraphQL APIs

GraphQL is a query language used for APIs that provides a more efficient and flexible way of querying data. With GraphQL APIs, the client can specify the exact structure for the data needed, and the server will respond with that data in JSON format. This is unlike a REST API, where the server decides the structure in which data is returned.

One of the biggest advantages of GraphQL APIs is that they allow clients to request exactly the data they need rather than returning a fixed set of data. This reduces network overhead and improves performance. GraphQL APIs also combine data from multiple sources, such as databases, microservices, or external APIs, into a single API. This simplifies the client-side code and reduces the number of network requests needed.

One downside: GraphQL is relatively new, and the ecosystem is still evolving, so finding experts in this technology is not as easy as finding developers for REST APIs.

WebSocket APIs

WebSocket APIs are used to establish a persistent connection between a client and a server. This allows for real-time communication between the two, with the server able to push data to the client without the need for repeated requests.

WebSocket APIs initiate requests like any other API, but they do it only once to establish a connection. The first request and response communication between the client and the server is called a handshake. After the handshake, the client and server can exchange information easily without the need for multiple requests every time. Multiplayer gaming is a good use case for WebSocket APIs.

Besides real-time data, WebSocket APIs offer low latency communication, reduce network overhead, and are not tied to any specific data format or protocol. However, these APIs need a persistent connection between the client and server, which can consume more resources than traditional HTTP requests.

Best Practices for Using APIs

APIs are used in most software products, and their effective use can improve product quality significantly. With the help of a few best practices, product managers can make sure that APIs are used in a secure, efficient, and reliable manner.

Identify clear use cases before choosing an API

Defining clear use cases helps determine the functionality and features required in the API and ensures that it aligns with the overall product strategy. For example, you can use a RESTful API as well as a WebSocket API for a live chat feature; knowing how you want your API to function will help you choose between the two.

Get Buy-in From Your Development Team

Your development team is a major stakeholder in your product. They will set up the API and make sure it is working as expected, so getting their buy-in before you choose an API is important.

When you have shortlisted a few APIs, get buy-in from your development team by giving them access to the API documentation from all providers. They will go through the technical documentation, sample code, and tutorials and determine which API is easier to implement.

Make Sure You Have Security Protocols in Place

APIs can expose sensitive data, so it is crucial to ensure that the API is secure. This includes using authentication mechanisms for API security, such as API keys or OAuth 2.0, limiting access to specific endpoints, and implementing rate limiting to prevent overuse of the API. Some of the steps you can take to improve API security include:

Authenticate users - Use API keys and tokens to authenticate apps, users, and devices that have access to the API.
Encrypt API requests and responses - Most APIs use HTTP, so you can encrypt data using the Transport Layer Security (TLS) protocol or the Secure Sockets Layer (SSL) protocol.
Store API keys separately - If someone can gain access to your API keys, they can use and abuse the API. Store your API keys outside of your application's source code. This way, even if your source code management system is compromised, your API keys remain safe.
Monitor API usage - APIs are vulnerable to distributed denial-of-service (DDoS) attacks, i.e., a bad actor can overwhelm your system with multiple requests. You can overcome this challenge with the help of rate limiting and continuous monitoring of API usage.

Factors To Consider When Choosing an API

There are multiple API providers for every use case. Some API providers are more suited for specific use cases than others.

For example, an organization that sends out a few thousand emails per month may not need an API that's capable of sending hundreds of thousands of emails every week. So, you should consider a few factors when evaluating and selecting APIs for your products.

Uptime, Availability, and Response Time

Evaluate the reliability of the API based on uptime, availability, and response time. While you'd ideally want your API to be up 24/7, it becomes more important in use cases that affect people's well-being. For example, healthcare products that monitor heart rates and blood pressure or financial services products where people actively make transactions cannot afford even a few minutes of downtime. Such products use multiple APIs for various functions, so if you are about to introduce a new API in that ecosystem, make sure it is available around the clock.

To gauge an API's reliability, find user reviews and testimonials for the API provider and look into its ability to provide support in case of any issues with downtime.

Scalability

In use cases such as gaming and social media, there's always a chance of users generating an unexpected volume of data. If one or more of the APIs cannot handle such volumes and scale up in real time, your users will experience issues with the product.

See if you can gain access to a trial version of the API and test it firsthand for scalability. If you can't do that, look into the current customers of the API provider, as that would give you an idea of the load it can handle.

Developer Support

Evaluate the level of developer support supplied by the API provider. Look into the availability of documentation, tutorials, and other resources that the API provider offers to help developers. You want to make sure you go for an API that offers the best support for your developers.

Think of use cases such as payment processing APIs and healthtech APIs. Payment processing APIs involve complex financial regulations and security protocols. Healthtech APIs involve sensitive patient data and are subject to strict regulations. In both cases, your developers need clear documentation and reliable support to integrate these APIs into your products and ensure regulatory compliance.

How To Test a Newly Added API

It's important to test a new API to make sure it works as intended and also to make sure that the addition to your API ecosystem has not affected the other functions of the product. In addition to their standard procedure for testing new APIs, ask your development team to:

Test the API Endpoints

Start by testing the API endpoints to ensure that they are responding correctly. Use tools such as curl to send requests to the API endpoints and check the responses. Make sure that the responses match the expected results.

In case of errors:

Review the error message and identify specific error codes or error descriptions. This can help you understand which part of the API request failed.
Check the API documentation to verify the correct syntax and parameters.
Check your input data for any missing or incorrectly formatted fields.
Check the API server status to make sure it's up and running.
Debug your code or try testing the API request with a different tool or library to see if the issue persists.
Contact the API provider if the error persists.

Test With Different Inputs

Test the API with different input values to ensure that it handles all possible inputs correctly. This includes testing with different data types, edge cases, and invalid inputs.

For example, if your API is supposed to calculate the square root of a number, test with:

Test case 1: Input: 49 | Expected Output: 7
Test case 2: Input: 9 | Expected Output: 3
Test case 3: Input: 0 | Expected Output: 0
Test case 4: Input: "abc" | Expected Output: Error response with the message "Invalid input type"

If the output is not as expected, go back to checking API documentation or debugging your code.

Test for Errors and Exceptions

Test the API for error handling and exceptions. This includes testing for error codes, error messages, and exception handling. Ensure that the API returns appropriate error responses when errors occur. Correct error messages help end users as well as your developers solve issues quickly.

If the error message should be "Invalid input type" and it shows up as "408 Request Timeout Error," refer to the API documentation and make the necessary adjustments.

Test Performance and Scalability

Test the API for performance and scalability. This includes testing the API with high loads and ensuring that it can handle a large number of requests without any performance issues. Load testing will also tell you how the API's speed is affected when handling a large number of requests or large volumes of data.

Test Security

Test the API for security vulnerabilities. This includes testing for SQL injection, cross-site scripting (XSS), and other common security issues. Ensure that the API uses secure authentication and access control mechanisms.

Conduct User Acceptance Testing

Finally, conduct user acceptance testing with a small group of users to ensure that the API meets their needs and requirements. This could be your beta testers, or you can do a phased rollout of the new version of the app that contains the new API and test the new version's performance on a small portion of your customers.

Use Automated API Testing Tools

Testing endpoints, security, user acceptance, etc., manually can be a resource-intensive task, and it's simply not scalable if you plan to add multiple APIs to your product. Use automated testing tools such as Postman and Katalon for increased efficiency and test APIs at scale.

Using automated testing tools also helps you reduce the risk of human error, get faster feedback on the quality of your APIs, and detect bugs early before you go live.

Choose APIs That Offer the Best Developer Support

There are a lot of concerns you have to address when it comes to choosing third-party APIs to introduce new features to your product. You want the API to work seamlessly with your product, keep up with user expectations, and live up to your standards of security. When comparing different options, look at their user reviews, their ratings on platforms such as G2 and Capterra, and the documentation and tutorials they provide.

If two or more API providers have similar features, ratings, and pricing, go for the one with the best developer support. For example, if you want a chat API, and are conflicted between two or more options, choose one that offers thorough documentation and tutorials. Your developers and users will thank you for it.