What is an API?
API is the acronym for Application Programming Interface, which is a software intermediary that allows two applications to talk to each other. It is the part of the server that receives requests and sends responses. Each time you use an app like Facebook, send an instant message, or check the weather on your phone, you’re using an API.
Application programming interfaces consist of two components:
- Technical specification describing the data exchange options between solutions with the specification done in the form of a request for processing and data delivery protocols
- Software interface written to the specification that represents it
Each API contains and is implemented by function calls (language statements that request software to perform particular actions and services). Function calls are phrases composed of verbs and nouns and are described in the API documentation. For example:
- Start or finish a session
- Get amenities for a single room type
- Restore or retrieve objects from a server.
What Is an Example of an API?
Imagine you’re sitting at a table in a restaurant with a menu of choices to order from. The kitchen is the part of the “system” that will prepare your order. What is missing is the critical link to communicate your order to the kitchen and deliver your food back to your table. That’s where the waiter or API comes in. The waiter is the messenger – or API – that takes your request or order and tells the kitchen – the system – what to do. Then the waiter delivers the response back to you; in this case, it is the food.
Here is a real-life API example. You may be familiar with the process of searching flights online. Just like the restaurant, you have a variety of options to choose from, including different cities, departure and return dates, and more. Let us imagine that you’re booking you are flight on an airline website. You choose a departure city and date, a return city and date, cabin class, as well as other variables. In order to book your flight, you interact with the airline’s website to access their database and see if any seats are available on those dates and what the costs might be.
Other examples of APIs we use in our everyday lives are
- Weather Snippets: Google utilizes APIs to display relevant data from user search queries.
- Pay with PayPal: Just like with logging-in using a social media service, the “Pay with PayPal” functionality is built with APIs to ensure that the end application can only do what it needs to, without being exposed to sensitive data or gaining access to unintended permissions.
- Twitter Bots: Twitter bots are accounts that automatically tweet (or retweet), follow, and send direct messages based on software instructions. Twitter API can also tell bots when something specific happens on the platform.
Types of APIs
There are two broad types of APIs
- APIs by availability (release policies)
- APIs by use cases
APIs by release policies
In terms of release policies, APIs can be private, partner, and public.
Private APIs: These application software interfaces are designed for improving solutions and services within an organization.
Partner APIs: Partner APIs are openly promoted but shared with business partners who have signed an agreement with the publisher.
Public APIs: Also known as developer-facing or external, these APIs are available for any third-party developers. A public API program allows for increasing brand awareness and receiving an additional source of income when properly executed.
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.
Operating systems APIs: This group of APIs defines how applications use the resources and services of operating systems.
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.
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.
API specifications/protocols
The goal of API specifications is to standardize data exchange between web services. In this case, standardization means the ability of diverse systems, written in different programming languages and/or running on different OSs, or using different technologies, to seamlessly communicate with each other.
Remote Procedure Call (RPC)
Web APIs may adhere to resource exchange principles based on a Remote Procedure Call. This protocol specifies the interaction between client-server based applications. 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.
SOAP is mostly used with enterprise web-based software to ensure 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)
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 architecture 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 follows 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 support multiple formats for storing and exchanging data is one of the reasons REST is a prevailing choice for building public APIs these days. 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.
GraphQL
The need for faster feature development, 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 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.
API documentation
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. Well-written and structured API documentation that explains how to effectively use and integrate an API in an easy-to-comprehend manner will make a developer happy and eager to recommend the API to peers.
The API documentation is a reference manual with all needed information about the API, including functions, classes, return types, and arguments.
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
- SDK examples (if SDKs are available) illustrating how to access the resource, etc.
Documentation may be static and interactive. The latter allows for trying out APIs and see return results and usually consists of two columns: human and machine. The human column contains API descriptions, and the machine one 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.
The Importance of APIs
With a focus on modern B2B usage, an application programming interface can be a critical component to integrating data flows with customers and partner systems. It can even add increased flexibility to traditional types of robust exchange such as managed file transfer (MFT) and EDI.
Exchanging documents as part of dynamic business transactions like purchase orders (PO), for instance, points to an evolution of the B2B e-commerce landscape.
From providing multiple industries with improvements in speed, agility, consistency, and accuracy, companies continue to recognize the potential of extending and integrating application data flows via APIs, allowing for smoother business process integration across applications in conjunction with other types of B2B technology.
APIs are integral to running a data-driven business nowadays. They allow the line of business users and IT to leverage software and applications to increase productivity and improve the bottom line. From social collaboration tools to more innovative approaches to customer outreach, taking advantage of APIs can prove dividends within the enterprise.
Conclusion
The role of APIs is considerably greater if we look at it not only from the software development angle but also from the business collaboration angle. These machine-readable interfaces for resource exchange are like delivery services that work under the hood and enable that needed technological connectivity. More than 60 percent of the participants in the Current State of API Integration 2018 report agreed that API integration is critical to their business strategy. The study also suggested over 50 percent of all businesses would partner via APIs.
In this regard, the two main tasks for decision makers and developers are to select the API that works for a company’s specific business needs and understand how to effectively use it.