APIs are so important for anyone who builds software and we talk about our SMS APIs a lot! So let's go back to development basics, with everything you need to know about APIs.
And better yet – we asked an expert to break it down. So read on for everything you need to know about APIs in programming.
Application programming interfaces (APIs) are an increasingly crucial aspect of software development, especially as infrastructure grows more complex. Software systems use APIs to share data and enable the different components of a system to work together.
You can also use APIs to inject specialized knowledge and data from other systems into yours without needing to build in that knowledge yourself. For example, if your fitness app offers a weekly running plan for users, you can integrate an API that provides short message service (SMS) functionality. The API enables your app to send reminders to users about when to run.
This article explains what APIs are and what benefits they offer. You’ll also learn some tips and best practices on how to design and use APIs more effectively.
What is an API?
Think of an API as a messenger or go-between. The interface enables different pieces of software to communicate with each other according to defined rules and protocols. Because an API connects the various components of a system, it makes application development smoother and more flexible. You can add or update a service without needing to write all the code yourself.
Because APIs can help you expand your software systems, they offer multiple benefits to your business. The following are some example use cases.
Enabling shared data
One of the key benefits of APIs is that they enable applications within your organization to share data.
For example, suppose your organization has a central HR system that contains employees’ data (first name, last name, date of birth, etc.), but you have other travel management and payroll systems that need employee information. You can use APIs from the HR system to connect to the travel management and payroll systems to share necessary employee data. This way, the HR system acts as the single source of truth of your data. If you had to maintain multiple copies of employees’ data in each system separately, it would be challenging to constantly update that data across all the systems.
Increasing business opportunities
Another benefit of APIs is that you can use them as a mechanism to expose, or make available, your internal services to the outside world. This can provide enormous financial opportunities for your business.
One example of this is the Uber Ride Request Widget, which developers can add to their applications to request Uber bookings. The widget uses Uber APIs to make the bookings. With this widget, Uber is gaining massive market penetration by increasing its service delivery channels. If Uber had restricted its APIs to internal use only, it would have missed this additional avenue for business growth.
Enabling cross-platform integrations
In the current IT ecosystem, it’s common for systems to be built with several programming languages, such as Python or Java, and hosted across multiple operating systems such as Windows or Linux. If those different components needed to communicate directly, it would be almost impossible.
APIs provide you with a unified communication protocol to solve this problem. With industry-defined protocols, different systems built in different programming languages can communicate easily and without confusion.
Controlling data and intellectual property
A side benefit of using APIs is that you can protect and control your intellectual property. Instead of exposing all the implementation details of your business logic to external consumers (which risks you losing competitive advantage), you only reveal the input side of your API.
OpenAI manages this with its GPT-3 APIs. GPT-3 is an artificial intelligence model that can generate content with a language structure with high accuracy. OpenAI is not exposing the actual GPT-3 models to the users. Instead, exposing the models as an API gives OpenAI better control over the models’ usage. If a usage violation occurs, OpenAI can easily revoke the API access, and the offending user is immediately blocked.
How do APIs work?
Now that you know some of the advantages of using APIs, following are more details about how these interfaces operate.
Servers and clients
There are two parties involved in using an API. The API server is the backend system making the API available for use. The API client, or consumer, is the application using the API.
Types of APIs
There are multiple API protocols. The most common types are detailed below.
Representational State Transfer (REST)
REST is the most famous API type, known for its ease of use. It makes backend data available in simple formats such as JSON and XML. The most commonly used HTTP request types with REST APIs are:
- GET: To read a resource
- POST: To create a new resource
- DELETE: To delete a resource
- PUT: To update a resource
Remote Procedure Call (RPC)
The RPC protocol enables the execution of one function in one context from another function in a different context. It’s similar to calling a local function in your program from another function. The difference is that RPC works in the HTTP context to enable “remote calling.” The RPC protocol has gained popularity due to its high performance. A recent improvement on this protocol is gRPC, developed by Google.
Simple Object Access Protocol (SOAP)
SOAP is an XML-based web communication standard over HTTP. This protocol communicates through messages consisting of an envelope tag containing the message, a body (for request or response), and a header for any extra information. The SOAP protocol is language agnostic, with built-in error handling and support for many security protocols.
GraphQL
GraphQL is an API standard developed by Facebook that enables clients to describe precisely how they would like to retrieve it. Instead of the client sending multiple requests to build the required data structure, GraphQL utilizes the querying technique to enable the requestor to ask for an exact JSON response structure that the server should return. The main benefit of GraphQL is its flexibility, which allows clients to build sophisticated queries without needing the server’s development team to create an API for each requested response structure.
APIs vs. Endpoints
It’s essential to differentiate between two related concepts: the API and the endpoint. The API describes the protocols that allow a client to communicate with a server, while the endpoint is the URL or other entry point that enables the API to manage communications. The endpoint is where the API accesses server resources to handle requests and responses.
For example, ClickSend supports various APIs such as Email to SMS, Countries, and Fax. Under each API, there are several related API endpoints. The Fax API has endpoints for sending a fax and for calculating the total price for fax messages sent.
Note: While you’ll always invoke API endpoints, you’ll hear technical people commonly say “calling an API,” which means calling an API endpoint. Do not let this confuse you.
API security
API security is a must. You might want to grant access to a specific group of users, or you might want to control what access level each user should have. To do this, you’ll need to factor security into your design. There are three main things to consider when designing a secure API.
Authentication
You’ll need to ensure that each client who performs a request to your API is allowed to do so.
There are several ways to authenticate API clients when calling an API. One way is to generate a unique key for each client and require them to send it whenever they call the API. When you receive the request from a client, you’ll verify it against their unique generated key and accept or reject the API call based on the validation request. The main drawback of this approach is that the server application will be responsible for managing the clients’ keys.
Another way is by using a third-party trust server. Your API “trusts” a third-party server. That is, it registers every expected API client in the trusted server. The server issues a client ID and a client secret for each client to authenticate themselves.
Whenever a client application wants to make a call to the API server, they call the trusted server first using the client ID and client secret. If the credentials are valid, the trusted server generates a time-limited access token that it can send to the API server.
When the API server receives the access token, it validates the token using the digital signature to ensure the token is generated from the trusted server. If so, the API server accepts the request and returns the response. If not, it rejects the token.
The main benefit of this approach is that it outsources the credentials management overhead to a third party. Typical protocols for this approach are OpenID Connect, SAML 2.0, and OAuth 2.0.
Authorization
After you’ve authenticated your API clients, you’ll need to authorize them to give them the “just enough” access they need—no more, no less.
For example, suppose you build an API that enables users to retrieve employees’ details. You might want to control what employee attributes each client application should be able to see. For the payroll application, you might want to make the employee salary available. If the API client is a travel system, you might want to only expose the name and passport number.
As noted earlier, there are several methods to authorize API clients depending on the authentication method you use. For example, if you authenticate the clients using client keys, you can assign an access level to each API key. When you receive the API call from the client, you can resolve the corresponding access level based on the attached API key and control what data you expose to the client from the business logic code in your backend.
On the other hand, if you use a trust server-based approach to authenticate your clients, you can ask your trust server to attach a “role” in the authentication token that your server generates to the API client. When the API client sends you the authentication token, your server API will extract it and use it to resolve the access as described earlier.
Encryption
The final aspect you’ll have to consider in your API design is encrypting the connection between the API client and the API server. You can do that by using SSL certificates. Encrypting the client-server connection ensures that no one in between can listen to the communication and steal the data, which is known as a man in the middle attack.
API best practices
If you’re using an API, you should follow industry best practices to ensure a high-quality product. Some common elements to consider are included below.
API specifications
Since your API will support specific input formats, output formats, and error messages, it can become cumbersome to coordinate these moving parts with the API clients.
There are several standards to address this issue. Examples include the OpenAPI Specification for REST APIs and WSDL for SOAP. These are typically created as separate endpoints in your API.
Clients can use these endpoints to generate the necessary client-side code to call the API. This way, you’ll save the developers time when using your API.
Throttling
Some APIs can get heavy traffic, degrading the overall system performance.
To address that, you need to use a throttling mechanism. Define a specific usage limit over your API, say 200 calls/minute. Whenever your system starts to receive more than 200 calls/minute, it will tell the API client to wait before sending further requests. A common method is to use the HTTP error 429 Too Many Requests.
Error codes, logging, and monitoring
Like any software system, your API will have errors and issues for several reasons, such as client request format, connectivity difficulties, and internal server errors.
You need to return clear error codes to the API client indicating what happened to enable troubleshooting at the client end. You also need to log and monitor these errors so that your operations team can resolve them.
Pagination
If your API returns a large response object, you should paginate that response to avoid overloading the system. Say you have an API endpoint that will return the list of all the books in a library. Each response object contains details about the book, including the title, author, plot, and reviews.
If you build an API endpoint to return all the books in one request, your response object will become so large that it will most likely cause timeouts and crashes at the client end and memory overload at the server end. Using pagination solves this problem.
Instead of returning everything in one response object, divide your response object into several “pages” where each page is of a limited size, say 100 books. With each request, the API client will indicate which page it would like to receive: page 1 for books between 1 and 100, page 2 for books between 101 and 200, and so on. This way, you can serve small, efficient responses to your API clients.
Caching
If your API returns a specific response too many times, you can cache it. Caching enables you to store repeatedly accessed objects in a fast retrieval storage technology.
Instead of fetching your data from traditional storage, which can take 200 ms to retrieve, you can store the most accessed object in a cache to retrieve it quickly whenever needed. You’ll achieve a lower response time with a cache, such as 20 ms. This improves the user experience because it makes the applications load faster.
Conclusion
APIs can help you revolutionize your software systems. They enable more universal communication and improve your offerings to consumers while helping you safeguard your intellectual property.
The important thing is to make sure you’re managing your APIs properly, especially the security aspects of them, while following industry best practices for their design and usage. Doing so will make your APIs a true asset to your business.
Third-party companies also provide APIs to help you improve your system. For instance, ClickSend enables companies to have faster, smoother internal and external communications via SMS, email, text-to-speech voice calls, and messaging channels like WhatsApp. You can learn more about ClickSend’s API offerings in its documentation.
About the author
Mohammed Osman 🇸🇪 Twitter: @cognitiveosman
Mohammed Osman is a senior software engineer who started coding at the age of thirteen. His core skill set is a .NET ecosystem with a strong focus on C#, Azure, and data science. He enjoys the soft side of software engineering and leads scrum teams, and he shares coding and career tips on his blog.
