What is an API in Software Development? Types, Protocols, Examples

So, what is the meaning behind the API acronym? “API” stands for Application Programming Interface. An API allows various pieces of software to exchange data with each other without human input. This is especially convenient when using a ready-made solution as a base, which is easier than creating your own from scratch.

Streaming service Spotify, for example, has created an open API that gives access to playlists. Based on this, the developers created dozens of services that supplement and expand the capabilities of the service. Here are some of them:

• Every Noise at Once is an explorable, listenable acoustic map of the 1300+ genres of the world of music that uses the Spotify Web API to play track previews.
• Music Popcorn uses Spotify API to provide music clips as visualization of the music space, allowing people to explore and learn about the many different music genres.

Developers receive free access to music archives and, based on them, can bring new deals to life. In return, the service constantly attracts users who have the opportunity to make listening to music more personal. As a result, API is a win-win solution for everyone. Integrating AI text-to-music capabilities into APIs opens up innovative opportunities for developers to create applications that transform written content into unique audio experiences, enhancing user engagement.

It’s no surprise then that 90% of developers use APIs in some capacity. Here at MindK, we use APIs almost every time we develop a software product. Although the main consumers of APIs are software engineers, API development is driven by business needs. When implemented correctly, they can make your organization more efficient and generate value via cost-saving or direct monetization.

Choo i Skyen uses APIs to make its courses available for other platforms. They also enable a highly scalable modular architecture.

Why use APIs: how API development creates business value

Exchanging data between businesses has become known as the API economy. This term refers to using APIs and microservices to make business services and data more scalable, accessible, and profitable.

Expedia Travel, for example, makes about 90% of its revenue via an API that allows other apps to book flights, hotel rooms, and rental cars. eBay makes about 60% of sales via an API that lets people buy goods without visiting the marketplace. Around 50% of Salesforce’s revenue comes from an API that empowers custom CRM systems.

According to the Markets and Marketers report, the API management market size is expected to grow from $ 4.5 billion in 2022 to $13.7 billion by 2027. There are a number of reasons why a business should consider API development services:

• Better security. APIs control access to valuable data. Authorized users can only perform specific actions. A well-designed API can protect your system against all kinds of attacks and traffic spikes.
• Streamlined architecture. With APIs, you can develop your backend independently from UI. This allows you to implement business logic once and make it available on iOS, Android, and Web, or even rewrite your UI using a newer framework without affecting the backend. Multi-platform mobile development is simply too slow and expensive without APIs.
• Easier testing. With API tests, you can check the app’s business logic before your UI is ready and uncover security issues much earlier. Automated API testing can save you a ton of money – fixing bugs later in the development process becomes more and more expensive.
• Higher development speed. APIs free you from building everything from scratch as your developers can integrate features and data provided by other apps. Many successful apps like Zapier or Hootsuite are based on the creative usage of third-party APIs.
• Easier integrations. Most companies rely on a diverse set of software in their daily lives. Integrating them into a single system provides a huge value for an organization. And while larger vendors make their APIs available to the public, it’s rarely the case with custom and niche software. A well-designed API can give your product a competitive advantage or help you transform internal business processes.
• Better scalability. Instead of creating huge monolithic applications, you can build complex systems from independent components that communicate via APIs (this is about microservice architecture). Each service can be developed by a separate team using a set of technologies that are most appropriate for the task. What’s more, each service can be scaled independently (for example, allocating more resources to a particular service if it experiences high traffic).
• Easier compliance with GDPR and other regulations.

Sounds great, right? Now that we know exactly what the API is, it’s important to mention that there are also different types of APIs.

EMR stystem that uses APIs for a two-way HIPAA-compliant integration with Salesforce.

What are the different types of APIs?

By availability, APIs are grouped into five types that are often used in web-based applications:

• Open APIs. As long as these APIs are freely available, there are no restrictions on accessing them. This means that a public API may be used by both developers within the organization that released the API and developers outside of the organization who choose to register to access the interface.
• Public APIs. Public APIs are very similar to open APIs, except they usually come with a cost. This also implies that they normally include some kind of authentication or permission key to track usage. However, not all public APIs are for sale. Some public APIs can function similarly to internal APIs as part of a wider ecosystem. Salesforce’s API, for example, allows data to be imported and exported into the Salesforce platform.
• Internal APIs. They are also called Private APIs. They are designed primarily for internal use within a company. Internal APIs are easy to create and they don’t need to be as robust as those APIs meant for public use.
• Partner APIs. Partner APIs restrict who can use the service. They can be both free and paid. Because partner APIs are only made available to specific parties, they tend to have more stringent authorization, authentication, and security policies. Making an API available to only a few partners allows companies to maintain an API as safe as possible. It’s a decent compromise between being absolutely private and completely public.
• Composite APIs. They combine multiple data or service APIs. They enable developers to access several endpoints in a single call. Composite APIs are useful in a microservices architecture design, for example, when you need information from many services to complete a single task. But how can APIs do all that?

API mechanism: how does an API work under the hood?

The working principle of API is quite simple. On the back-end, the Application Program Interfaces sit in the middle of different entities, usually called a client and server. The application that sends the request is known as the client, and the application that sends the answer is known as the server.

For better understanding, consider the analogy of home electrical networks. When you want to use an electrical device, you just plug it in and everything works. You are not trying to connect the wires directly to a power source – this makes no sense and unless you are an electrician, is difficult and dangerous.

An API is considered a middleman between a client and a server and allows these two entities to exchange information.  Here is what it looks like in practice:

• A client application initiates an API call, often known as a request, to obtain information.
• APIs collect the data, prepare it for export, and send it to another without compromising accuracy or security.
• API after collecting the data and preparing it for export places a call to the third-party server or application.
• The server responds to the API by sending the requested data.
• API, in turn, delivers the obtained data to the client app.

When you purchase online, for instance, you’ll most certainly come across a “pay with PayPal” option at the checkout. This is a classic API example. The online store does not directly access your PayPal account during the checkout process. Instead, it routes the purchase order to the PayPal API, which handles the rest of the transaction and provides a response.

This raises the next question  – how do APIs serve as a bridge between so many different solutions without being too complex to be used across industries? The simple answer is that it employs very strict rules, called protocols.

Knowing the rules: API protocols and their types

A protocol is an agreed-upon collection of rules that regulate how two software products should communicate with one another via an API. Let’s review some of the most commonly used types of API protocols:

• Simple object access protocol (SOAP)

SOAP was developed by Microsoft and is considered a lightweight protocol to exchange structured information in a decentralized, distributed environment. The SOAP message has three main building blocks – an envelope that encapsulates all the data, a header that involves additional information; and a body that includes the details about the message.

SOAP defines an extensible communications architecture using extensible markup language (XML) technology. XML is a basic and highly adaptable text format that is commonly used for data storage and exchange via the internet.

XML offers a set of principles for encoding documents in a format that can be read by both people and machines. This makes SOAP less flexible compared with other protocols. Moreover, to fulfill each operation and adhere to the XML format for each message delivered, a large amount of code must be written.

SOAP can be delivered via a number of protocols (like HTTP, SMTP, and Transmission Control Protocol), allowing communication between applications written in various programming languages.

SOAP is widely utilized by enterprise applications, payment gateways, CRM, and financial and communications services due to the built-in security and transaction compliance that conforms with various enterprise demands. One of the most used SOAP APIs is PayPal’s public API.

• Representational State Transfer (REST)

REST is not an official protocol but a recommended set of principles that is rather flexible. The flexibility is primarily achieved by removing the dependency on XML and following certain architectural principles:

• Client-server architecture: the interface is separate from the backend and data storage. This enables flexibility and allows separate components to evolve independently.
• Statelessness: between requests, no client context is kept on the server.
• Cacheability to avoid direct client-server interaction: as clients can cache responses, a REST API response must state clearly whether it can be cached or not. This allows web browsers to save the response received locally and retrieve it on a regular basis to improve efficiency.
• Layered system: API will function properly whether communicating directly with a server or via an intermediate such as a load balancer.

Source: quora.com

Those web APIs that follow these REST architectural constraints are called RESTful APIs. RESTful API provides messages in a variety of forms, including plain text, HTML, YAML, XML, and JSON.

REST is a popular choice for establishing public APIs these days for its flexibility in handling many formats for storing and sharing data. REST is still by far the most commonly used API architectural approach today, with a stunning 93.4% adoption rate.

• Remote Procedural Call (RPC)

RPC protocols are the most fundamental and early Application Programming Interfaces. The objective of an RPC is to allow a client to run code on a server. There are XML-RPC which uses a specific XML format to transfer data and JSON-RPC which makes use of JSON instead of the XML format.

Over the years, RPC has served as a core technology for various successors. One variation is Google Remote Procedure Call (gRPC), an open-source solution introduced in 2015, about 35 years after RPC was invented. Google created gRPC to address RPC’s shortcomings. Interoperability, HTTP/2 support, and Protocol Buffers support are among the new features. A lightweight alternative known as distributed remote procedure call (DRPC) has recently emerged.

• Graph query language (GraphQL)

The necessity for rapid development, more efficient data loading, and increased use of mobile devices forced developers to explore other methods of software architecture. GraphQL, which Facebook developed for internal usage in 2012, has now become a popular approach used by companies like Shopify, GitHub, Pinterest, and Coursera.

This protocol is designed to give users the exact data they need—no less, no more. GraphQL is a developer-friendly language that enables building fast and flexible APIs, including composite APIs.

One more reason for its popularity is that GraphQL API technology meets the demanding requirements of today’s frontend apps. It is perfect for UI components, allows push real-time updates to the frontend, and involves static typing and validation.

GraphQL, as a REST alternative, allows developers to create requests that extract data from various data sources in a single API call. Moreover, GraphQL can be used on top of your existing infrastructures, such as REST, SOAP, or existing databases. This allows organizing data into a clean, unified API and querying it all at once.

With all these benefits, it’s not surprising why GraphQL adoption increased by 400% in one year. Industry analysts predict that number could rise from 30% to 50% in the next 3 to 4 years.

However, no matter how many options an API provides for building or enhancing software products, it would be a worthless piece of code if developers didn’t grasp how to deal with it. This is where API documentation enters the battlefield.

What is the API documentation and why does it matter?

API documentation is a technical guidebook that explains how to consume and integrate efficiently with an API. It is a detailed technical deliverable that may include code samples, technical writing, or case studies that demonstrate how developers can use an API successfully.

API documentation was not something that developers paid much attention to when releasing code a few years ago. However, it has evolved into one of the crucial factors determining the success of your API today. Good API documentation allows:

• Proper maintenance and faster updates. Documentation allows the internal staff to understand every detail of your resources and techniques, making maintenance and upgrades more efficient and precise.
• Reduces the time spent on user onboarding (including external partners or internal developers). Newcomers may begin being productive right away and will not be dependent on others.
• Reduces the amount of effort (and frustration!) spent learning how to use the API and decoding unexpected errors.
• Save time for clarifications. Due to a lack of proper documentation, developers will rely on the development or support team to guide them when attempting to use or integrate with an API.
• Increase the engagement. The efficiency of API documentation is directly related to its adoption. Having a simple and easy-to-understand API user manual will result in a large number of people using the API.

There is no one-fits-all variant for structuring API documentation. For instance, it may consist of three main parts:

• Overview that includes a summary of API functionality, and a Getting Started section with key steps to using the API.
• Developer’s guide that involves Use cases, API endpoints, sample requests, request parameters, sample responses, error handling information and much more.
• User guide that contains instructions for connecting to the API. It should ideally include a walkthrough of API use cases to help new users understand how to make use of API functionality.

Just take a look at the Stripe API docs. It has almost established a standard in terms of thoroughness and browsability. Each endpoint operation is documented in human-friendly words, as are the parameters developers send to Stripe. Finally, a copy-paste request is displayed, along with an example response.

Source: stripe.com/docs/api

To standardize documentation structure and design, API specialists today employ several API documentation solutions like Swagger, Postman, ReadMe, Slate, and others.

An example of creating API documentation with ReadMe

Source: readme.com

What are the examples of API in our everyday lives and in business?

Examples of API are all around you, whether you realize it or not. When logging in with the help of Google, Facebook, Twitter, or any other social account on some application, it requires an API to connect the two platforms together. When you Google the weather and see a pop-up weather snippet right front and center on your Google search page, it’s a prime API example. When you book a trip on websites like Trivago or similar, the website uses an API to access information about available flights and hotels. This list could go on and on because examples of API are widespread throughout our everyday lives.

However, it is critical to note that APIs are used for far more than those examples could possibly demonstrate! This is especially true in business, where successfully storing and transmitting data is critical for day-to-day operations. If you look at our portfolio of projects, you’ll see that we apply API integrations to almost every project on the list.

For example, the system for pension and insurance calculations we developed for the Norwegian market. Norway’s pension system is complex – to comprehend pension payments, people must register in many systems and do calculations based on a complicated formula that is difficult and time-consuming. We developed a SaaS solution that provides Norwegian company employees with easy-to-understand retirement benefit schemes and pension calculations.

All these online calculations are made possible thanks to API integrations with Aksio and Norsk Pensjon insurance systems that always guarantee up-to-date data. The scheme is quite simple:

• A user on the Innmeldt website makes a request for pension calculations.
• Innmeldt API receives this request, validates it, transforms it depending on the request side, and sends a request to a Calculation engine.
• The Calculation engine takes input data and makes a request to North Pension to obtain the main values;
• North Pension returns data only for people older than 67 years, so the Aksio API is used to get the data for users who are 62-67 years old.
• The Calculator engine transforms received data from North Pension and Aksio into certain variables (they depend on the initial request side) and sends it to Innmeldt API.
• Innmeldt API gets the result from the Calculation engine and sends it to the user.

Another example is the intelligent TV and radio ad campaign management system AIM Analytics, developed for Converze Media Group, a direct-response advertising agency in the United States. The system tracks campaigns across marketing channels and provides accurate, up-to-date reports, with traffic numbers, cost per action, and buying data.

The reporting of performance metrics operates thanks to a number of integrations with third-party systems. Here are just a few:

• Integration with Media Monitors uses the SOAP protocol and file integration with BVS allows receiving data about TV or radio ads that have been played in a certain period of time.
• RESTful API integration with Marchex helps to obtain information about the list of phone calls to certain numbers (that are associated with the advertisement), the duration of the call, and the caller’s numbers.
• RESTful API integration with DRMetrix also helps to receive data about ad performance in a certain period of time.
• Integration with Google Analytics API is needed to get a list of users who visit the website.

All these integrations with third-party systems allow collecting valuable information for further analysis and the processing of large amounts of data without increasing staff, thus saving thousands of dollars annually. 

[Last but not least] Architecture also matters: what are the architectural approaches to API usage?

As we’ve already mentioned, one of the biggest benefits of API is that it allows going beyond the monolith to more distributed, service-based architectural patterns. There are two main architectural approaches for using APIs: service-oriented architecture (SOA) and microservices architecture.

As SOA is an older approach compared to microservice architecture, it may not be suitable for modern cloud-native apps. However, it still has a lot of advantages that make it an excellent choice in a variety of cases. To understand the difference, let’s review each of them.

Service-oriented architecture is a software design approach in which functionalities are separated and made available as different services via a network. SOA is often implemented via web services, which make the functional building blocks available via standard communication protocols.

SOA is less concerned with how to modularize an application but more with how to compose an application through the integration of distributed, independently maintained, and deployed software components. This way, the essential use case for service-oriented architecture is the ability to design an application by combining numerous independent services, each of which contains a distinct business or application logic.

In some ways, microservices are the next stage in the evolution of SOA. This architectural approach implies developing software as a suite of independent services, called microservices. All of these services are designed to support a single business function.

The microservices architecture is a different architectural approach in which an application is divided into smaller, independent components. Applying the application as a collection of distinct services simplifies testing, maintenance, and scaling.

Microservices are fully independent of one another, which means they may be developed in various programming languages and utilize various databases. There is no centralized service administration either; microservices communicate using lightweight HTTP, REST, or Thrift APIs.

Service-oriented architecture vs microservices

Source: dzone.com

Microservices are frequently seen as the ideal use case for containerization. In this case, each of these micro-services is deployed on separate containers. This offers an efficient structure of many services that are adaptable, portable, and platform-agnostic, allowing each service to run in its own process with different operating systems and databases.

‘So which architectural approach is the best to use today?’ you may ask. It’s hard to tell. It is mostly determined by the aim of the application you are developing.

SOA is better suited for large, complicated business applications that require integration with numerous applications. Workflow-based systems with a well-defined processing flow, on the other hand, are more challenging to create using SOA standards. Small applications are also unsuitable for SOA since they do not require a message middleware component.

Microservices, on the other hand, are better suited for smaller and well-partitioned web-based systems because microservices provide significantly more control. Because of a lack of messaging middleware, microservices are unsuitable for complicated applications.

Here at MindK, we analyze each project individually and weigh the pros and cons when deciding on the architectural approach to use. For example, one of our clients, America’s leading reputation management company, came to us with a decade-old legacy system for tracking online reputation. The architecture was difficult to maintain, required a lot of manual work, had unstable and unpredictable releases that slowed down the build and delivery process, and required overpaying for infrastructure support. After analyzing the project, the team decided to migrate the project to a microservice architecture as it allowed them to solve all these problems in one shot.

Our engineers implemented an automated CI/CD pipeline in Github Actions. The pipeline builds separate containers for every product component and loads them to a Docker registry. With the new infrastructure, our client saves around 14,000 USD. Releases became more predictable, secure, and faster.

Explore a detailed case study →

Is an API right for you?

When we evaluate APIs from both the software development and business collaboration perspectives, their importance grows significantly. APIs enable businesses to achieve goals that were previously impossible.

As you can see, we already rely on APIs without even realizing it. Whether you use an app to check the weather or to observe current traffic, these apps usually rely on APIs to retrieve this data. The primary task for decision-makers and developers in this regard is how to get the most of API advantages.  If you need professional help with API development or consultation about improving the architecture, the MindK team is ready to help. Just drop us a line.