What is API: Definition, Types, Specifications, Documentation
How does human communication happen? People can express thoughts, needs, and ideas through language (written and spoken), gestures, or facial expressions, right? At the same time, our interaction with computers, apps, and websites requires user interface (UI) components — a screen with a menu and graphical elements, a keyboard, and a mouse.
Software or its elements, on the other hand, don’t need a graphical user interface to talk to each other. To communicate and exchange data and functionalities, programs use machine-readable interfaces called APIs.
If you ever read tech magazines or blogs, you’ve probably seen the abbreviation API. It sounds solid, but what does it stand for? API stands for Application Programming Interface. This post will explain what APIs are, how they work, and why you should care about them in the first place.
Application Programming Interface: API explained
An API is a set of programming code that enables data transmission between one software product and another. It also contains the terms of this data exchange.
Check our video explainer to get acquainted with what APIs are in general.
The application programming interface must be clearly distinguished from a user interface. The user interface accepts data from users, forwards it to the API for processing, and returns the results to the user. The API does not interact with the user but processes the data received from one program module and transmits the results back to the other module. Here’s how it happens.
How do APIs work?
The working principle of an API is commonly expressed through the request-response communication between a client and a server. The client is any front-end application that a user interacts with. The server is in charge of backend logic and database operations. In this scenario, an API works as a middle layer between the client and the server, making it possible to send data requests and responses.
The Red Hat specialists note that APIs are sometimes considered contracts, where documentation is an agreement between the parties, “If party 1 sends a remote request structured a particular way, this is how party 2 software will respond.” This contract takes the form of an API specification or protocol — an architectural blueprint that describes the interface behavior and serves as a rough guide on how to build a particular API (we’ll talk about the most common API specifications later). Among other things, the protocol defines core API components.
API components: calls, keys, endpoints
An API call is a request a client app forwards to a server. It contains
- operations to be executed (for example, GET to retrieve a resource or POST to send data),
- authentication details — for example, an API key that identifies the client,
- additional parameters, and
- a destination address — the URL of the API endpoint.
An API endpoint is like an entrance to a place where a sought-after resource (data or feature) lives. The endpoint checks the API key and, if approved, sends back a response with the information on the operation status (error or success) and requested resources.
API vs webhooks
Often called event-driven or reverse APIs, webhooks enable one-way communication between apps. They don’t wait for requests, reacting instead to trigger events — for example, a credit card charge or a subscribe form submission. Once an event occurs, a webhook automatically performs a specific operation or pushes content from the server to the client’s URL.
Let’s say a hotel partners with Cloudbeds to use their property management system (PMS). With webhooks enabled, the hotel can subscribe to events it’s interested in — such as a new reservation creation or changes to booking dates. The PMS will instantly notify the hotel’s app of changes.
Webhooks work best for sending automated reminders, notifications, and real-time updates. They’re fast and relatively easy to set up. However, compared to full-fledged APIs, their lightweight relatives lack functionality, cannot handle intense and complex two-way communication, and have fewer security capabilities.
API vs SDK
While APIs let you connect your app with existing data sources and services, a software development kit or SDK is a suite of platform-specific tools (libraries, compilers, debuggers, code samples, etc.) and documentation that lets developers build an application faster and in a standardized way. Often, the SDK contains an API or a set of APIs. Conversely, you can build an API using the SDK.
For example, for those who want to have dynamic maps in their apps, Google provides Maps SDKs for web, iOS, Android, and cross-platform (Flutter) development. In turn, Sabre, one of the leading global distribution systems (GDSs), offers online travel agencies (OTAs) the SDK to build a customized app that integrates directly with the Sabre Red 360 booking platform.
API types
There are different types of APIs that can be categorized based on the ways they are available for use and according to their initial design purposes.
APIs by availability, aka release policies
In terms of release policies, APIs can be private, partner, and public.
Private APIs.These application software interfaces are designed to improve organizational solutions and services. In-house developers or contractors may use these APIs to integrate a company’s IT systems or applications as well as build new systems or customer-facing apps leveraging the existing infrastructure.
Even if apps are publicly accessible, the interface itself remains available only for those working directly with the API publisher. The private strategy allows a company to fully control API usage.
Partner APIs. This type of API is openly promoted but shared with business partners who have signed an agreement with the publisher. The common use case for partner APIs is software integration between two parties. A company that provides partners with access to data or capability benefits from extra revenue streams. At the same time, it can monitor how the exposed digital assets are used, ensure whether third-party solutions leveraging their APIs provide decent user experience, and maintain corporate identity in their apps.
Public APIs. Also known as developer-facing or external APIs, these APIs are available for any third-party developers. When properly executed, a public API program can increase brand awareness and provide an additional source of income.
There are two types of public APIs — open (free of charge) and commercial ones.
- Open public APIs, as the Open API Definition suggests, are those with all features public and available for use without restrictive terms and conditions. For instance, it’s possible to build an application that utilizes the API without explicit approval from the API supplier or mandatory licensing fees. The definition also states that the API description and any related documentation must be openly available. On top of that, these APIs can be freely used to create and test applications.
- Commercial API users pay subscription fees or utilize APIs on a pay-as-you-go basis. A popular approach among publishers is to offer free trials so clients can evaluate APIs before purchasing subscriptions.
Learn more about how businesses benefit from opening their APIs in our detailed article on the API economy.
Availability is only one criterion on which APIs are classified. Let’s look at them from a different angle.
APIs by use cases
APIs can be classified according to the systems for which they are designed.
Database APIs. Database APIs enable communication between an application and a database management system. Developers work with databases by writing queries to access data, change tables, etc. The Drupal 7 Database API, for example, allows users to write unified queries for different databases, both proprietary and open source (Oracle, MongoDB, PostgreSQL, MySQL, CouchDB, and MSSQL).
Another example is ORDS database API, which is embedded in Oracle REST Data Services.
Operating systems APIs. This group of APIs defines how applications use the resources and services of operating systems. Every OS has its set of APIs, for instance, Windows API or Linux API (kernel user-space API and kernel internal API).
Apple provides API references for macOS and iOS in its developer documentation. APIs for building applications for Apple’s macOS desktop operating system are included in the Cocoa set of developer tools. Those building apps for the iOS mobile operating system use Cocoa Touch — a modified version of Cocoa.
Remote APIs. Remote APIs define standards of interaction for applications running on different machines. In other words, one software product accesses resources located outside the device that requests them, which explains the name. Since two remotely located applications are connected over a communications network, particularly the internet, most remote APIs are written based on web standards. Java Database Connectivity API and Java Remote Method Invocation API are two examples of remote application programming interfaces.
Web APIs. This API class is the most common. Web APIs provide machine-readable data and functionality transfer between web-based systems which represent client-server architecture. These APIs mainly deliver requests from web applications and responses from servers using Hypertext Transfer Protocol (HTTP).
Developers can use web APIs to extend the functionality of their apps or sites. For instance, the Pinterest API comes with tools for adding users’ Pinterest data like boards or Pins to a website. Google Maps API enables the addition of a map with an organization’s location.
Most businesses use more than one API to connect applications and share information. Some end up needing an API management tool to help them control, distribute, and analyze different APIs.
Learn more about API management in our detailed article.
API formats and specifications
API specifications aim to standardize data exchange between web services. In this case, standardization means the ability of diverse systems written in different programming languages, running on different OSs, or using different technologies to seamlessly communicate with each other. Specifications differ across API formats — let’s briefly review the most common ones.
Remote Procedure Call (RPC)
Web APIs may adhere to resource exchange principles based on a Remote Procedure Call or RPC. This protocol specifies the interaction between applications based on the client-server architecture. One program (client) requests data or functionality from another program (server), located in another computer on a network, and the server sends the required response.
RPC is also known as a subroutine or function call. One of two ways to implement a remote procedure call is SOAP.
Service Object Access Protocol (SOAP)
SOAP is a lightweight protocol for exchanging structured information in a decentralized, distributed environment, according to the definition by Microsoft that developed it. Generally speaking, this specification contains the syntax rules for request and response messages sent by web applications. APIs that comply with the principles of SOAP enable XML messaging between systems through HTTP or Simple Mail Transfer Protocol (SMTP) for transferring mail.
Extensible markup language (XML) is a simple and very flexible text format widely used for data storage and exchange over the Internet or other networks. XML defines a set of rules for encoding documents in a format that both humans and machines can read. The markup language is a collection of symbols that can be placed in the text to delineate and label the parts of the text document. XML text documents contain self-descriptive tags of data objects, which makes them easily readable.
SOAP is mostly used with enterprise web-based software to ensure the high security of transmitted data. SOAP APIs are preferred among providers of payment gateways, identity management, and CRM solutions, as well as financial and telecommunication services. PayPal’s public API is one of the commonly known SOAP APIs. It’s also frequently used for legacy system support.
Representational State Transfer (REST)
The term REST was introduced by computer scientist Roy Fielding in a dissertation in 2000. Unlike SOAP, which is a protocol, REST is a software architectural style with six constraints for building applications that work over HTTP, often web services. The World Wide Web is the most common realization and application of this architectural style.
REST is considered a simpler alternative to SOAP, which many developers find difficult to use because it requires writing a lot of code to complete every task and following the XML structure for every message sent. REST sticks to another logic since it makes data available as resources. Each resource is represented by a unique URL, and one can request this resource by providing its URL.
Web APIs that comply with REST architectural constraints are called RESTful APIs. These APIs use HTTP requests (AKA methods or verbs) to work with resources: GET, PUT, HEAD, POST, PATCH, CONNECT, TRACE, OPTIONS, and DELETE.
RESTful systems support messaging in different formats, such as plain text, HTML, YAML, XML, and JSON, while SOAP only allows XML. The ability to handle multiple formats for storing and exchanging data is one of the reasons REST is a prevailing choice for building public APIs these days.
Social media giants and travel companies provide external APIs to improve their brand visibility even more. Twitter has numerous RESTful APIs; Expedia has both SOAP and RESTful APIs for its partners.
If you consider redefining your travel and hospitality business offering, dive deep into the world of travel and booking APIs with our dedicated article.
JavaScript Object Notation (JSON) is a lightweight and easy-to-parse text format for data exchange. Its syntax is based on a subset of the Standard ECMA-262 3rd Edition. Each JSON file contains collections of name/value pairs and ordered lists of values. Since these are universal data structures, the format can be used with any programming language.
JSON has been widely adopted thanks to the popularity of REST.
gRPC
gRPC is an open-source universal API framework that is also classified under RPC. Unlike SOAP, gRPC is much newer and was released publicly in 2015 by Google. With gRPC, the client application can directly call methods from a server application located on a different computer as if it was a local object. This makes it easier to create distributed services and applications.
Like SOAP and REST, the transport layer for gRPC is HTTP. However, similar to RPC, gRPC allows developers to define any kind of function calls, rather than selecting from preset options such as PUT and GET in the case of REST.
By default, gRPC uses protocol buffers instead of JSON or XML as the Interface Definition Language (IDL) for serializing structured data. Here, the developer needs to first define the structure of the data they want to serialize. Once the data structures have been specified, they use the protocol buffer compiler to generate the data access classes in the programming language of your choice. The data is then compressed and serialized in binary format at runtime.
Learn more about gRPC in our detailed article.
gRPC is mostly used for communication between microservices because it is available in multiple languages and has a high performance.
GraphQL
The need for faster feature development and more efficient data loading due to increased mobile adoption and a multitude of clients made the developers look for other approaches to software architecture. GraphQL, initially created by Facebook in 2012 for Internal use, is the new REST with organizations like Shopify, Yelp, GitHub, Coursera, and The New York Times, using it to build APIs.
GraphQL is a query language for APIs. It allows the client to detail the exact data it needs and simplifies data aggregation from multiple sources, so the developer can use one API call to request all needed data. Another special feature of GraphQL is that it uses a type system to describe data.
Apps using GraphQL control what data they need to fetch from a server, which allows them to run fast even when the mobile connection is slow.
You can see how GraphQL, REST, RPC, and SOAP are compared in the linked article.
API documentation and API requirements
No matter how many opportunities for creating or extending software products API gives, it would remain an unusable piece of code if developers didn’t understand how to work with it. While the API specification mentioned above dictates how to build an API, API documentation explains how to effectively use and integrate it,Well-written, structured, andeasy-to-comprehend docs with all the needed information about functions, classes, return types, arguments, and more, will make a developer happy and eager to recommend the API to peers.
Numerous content elements make good documentation, such as
- a quick start guide;
- authentication information;
- explanations for every API call (request);
- examples of every request and return with a response description, error messages, etc.;
- samples of code for popular programmatic languages like Python, Java, JavaScript, or PHP;
- tutorials; and
- SDK examples (if SDKs are available) illustrating how to access the resource, etc.
The detailed API requirements, which functional, nonfunctional, and implementation requirements, should also be clearly articulated in the documentation.
Functional requirements define what an API should do and how it’s going to do it. Nonfunctional API requirements describe how an API should perform in terms of a service-level agreement. For example, if you apply a particular security mechanism to an API, consumers who require a different security mechanism won’t be able to use this API. Finally, implementation requirements provide information on how to meet functional or nonfunctional requirements for a particular API implementation.
Documentation may be static and interactive. The latter allows you to try out APIs and see return results. It usually consists of two columns: human and machine. The human column contains API descriptions, and the machine column has a console to make calls and contains info that clients and servers will be interested in when testing the API.
Generation is the process of documenting APIs by developers and technical writers. The specialists may use API documentation solutions (i.e., Swagger tools, Postman, Slate, or ReDoc) to unify documentation structure and design.
API examples
Here are some examples of well-known APIs that use different protocols and specifications. Check their documentation to get more information and references.
Google Maps. It is no secret that Google is among the tech giants, and they have set the standards in the way other companies operate. Most websites that have an integrated map are using the Google Maps APIs.
Vulkan. Vulkan is a cross-platform API that works on the operating system level. It enables developers to create high-quality, real-time graphics in applications and drives the communication between an app and a graphical processing unit (GPU). Check Vulkan API documentation if you’re interested.
Skyscanner Flight Search. Skyscanner is a metasearch platform that lets travelers search for flights at the best rates from its database of prices. Also, Skyscanner provides its affiliate partners with a RESTful API supporting both XML and JSON as the data exchange formats. To improve security, they encourage partners to only use HTTPS protocol to make requests. You may check their documentation here.
WeatherAPI. This is a free geolocation and weather information provider with lots of different APIs that provide access to the weather forecast, IP lookup, sports, astronomy, geolocation, and other data. Developers can use either HTTP or HTTPS to request the JSON/XML RESTful APIs while taking advantage of detailed documentation.
Amadeus Travel APIs. Amadeus, another large GDS, offers a collection of REST and SOAP APIs that lets travel platforms search across and book with over 400 airlines, 150,000 hotels, 100 tour operators, 90 railways, 75 car rental companies, and more. APIs from their self-service suite perform several transactions in response to one request, hiding the complexities of booking flow from developers and speeding up the integration process.
For more details, read articles on Amadeus API integration and Sabre API integration based on our hands-on experience.
Yelp API. This is a GraphQL API that provides users with recommendations and reviews of the best restaurants, things to do, nightlife, and more. It uses the HTTP request method to access data from the servers. The API connects to data sources through endpoints, which developers can add to their apps. It uses JSON as the data exchange format.
Why to use an API?
APIs serve numerous purposes. Generally, they simplify and speed up software development. Engineers can set access to data or expand their apps with functionality (i.e., a recommender system, accommodation booking engine, payment processing, or image recognition feature) from third-party providers. But there are other reasons why you should consider APIs as a vital part of your business growth strategy.
Connecting internal systems. APIs allow you to integrate systems inside your business environment. It helps avoid data silos and facilitates information exchange between different departments.
Enhancing security. Many security flows become available due to APIs. Say, the single-sign-on (SSO) process, when a user can log in once to reach multiple services, is handled by a third-party Identity as a service Provider (IdaaS). By connecting to IdaaS through API, enterprises can strengthen their security measures while providing employees with convenient, one-click access to the company’s apps and resources.
Integrating IoT devices. APIs are key to creating an IoT ecosystem. Via APIs, apps pull information from connected devices and control them. For example, fleet management systems use APIs to activate vehicle telematics and receive information on a truck’s location, speed, driver behavior, etc.
Expanding a customer base. APIs let you programmatically connect with your B2B partners sharing inventory and services. For example, in the travel businesses, it’s essential for hotels, airlines, tour operators, and other suppliers to have APIs so that OTAs and travel management companies (TMCs) can distribute these products via their platforms.
Originally published at https://www.altexsoft.com.
