What are APIs? A Complete Guide

What Is an API?

Application program interfaces (APIs) are code that enables the communication between two software programs. APIs determine how a developer requests services from an operating system or application.

The three main types of APIs are:

• Private APIs—designed to enhance services and solutions within an organization. Even if the application itself is publicly available, the API is only available to developers directly employed by the publisher. Developers use private APIs to build applications or perform integration between systems.
• Partner APIs—made available to business partners who have an agreement with the API publisher. This is common for software integration between two companies. The partner accessing the API receives access to data or certain software features. The publisher receives a revenue stream and is responsible for ensuring that the API provides a good user experience.
• Public APIs—also known as external or developer-facing APIs, are available to any third-party developer. Public APIs can be free to use or commercial:
• Open (free) APIs—all features are public and use is not restricted by terms and conditions. The API can be used to build applications without purchasing a license or subscription. Any documentation related to the API is publicly available.
• Commercial APIs—usage is subject to paid subscription fees or a pay-as-you-go scheme. Publishers may offer free trials to allow users to evaluate the API before they purchase a subscription.

Want more tech news? Subscribe to ComputingEdge Newsletter Today!

What is The API Economy?

APIs have become an increasingly important product in the development market, with over 24,000 web-based APIs currently available in the ProgrammableWeb directory. Companies can choose if they want to provide open access to an API or restrict it to paid usage. The content provided through API channels can also be monetized.

The Business to Developer (B2D) model characterizes this market, with the management of corporate API resources known as the API economy. Some major aspects of the API economy include:

• Cloud computing—cloud computing enables the segmentation of software into components that can be reused, scaled, and connected to requests. As a result, APIs have shifted to more complex RESTful web-centric models, as opposed to the old RPC models, which were programmer-centric. APIs are also at the core of cloud automation, enabling developers to manage complex infrastructure as code.
• Integration of technologies—APIs play a key role in digital transformation, enabling the integration of disparate systems that support different technologies. APIs also help integrate hardware components, via the internet of things (IoT). By bridging between machine and human capabilities, APIs assist AI systems and help unify processes such as RPA (Robotic Process Automation). Emerging technologies will continue to utilize API integrations.
• Adaptive governance—involves setting up policies for managing the API life cycle. Policies used to be static rules and exceptions, but growing dependence on APIs now means that processes are constantly changing. API usage is dynamic and seasonal, so governance needs to adapt to changing business contexts. Artificial intelligence allows governance to be tweaked in accordance with historical data and API usage patterns.

Common API Examples

Popular examples of APIs include:

• Universal login APIs—allow users to login with a single profile across multiple websites, so they can be authenticated quickly and avoid having to set up new profiles for each service. For example, users can log in using details from their Google, Twitter, or Facebook accounts.
• Payment processing APIs—allow secure processing of payment information by a third party. A good example is the “Pay with PayPal” function available for many Ecommerce services. APIs allow customers to pay for purchases online while protecting sensitive information and blocking access to unauthorized individuals.
• Travel booking comparisons—thousands of flight and accommodation options are aggregated to point users to the cheapest options for a desired destination and date. Travel websites achieve this with APIs that connect multiple sources of information.
• Video APIs—enable the implementation of collaborative video experiences via a website or mobile application. Users don’t have to worry about complex handling of actions such as hosting, uploading, synching, and serving.

API Specifications and Protocols

API specifications standardize the exchange of data between web services. This means that different systems, which use different programming languages or run on different operating systems, can communicate with each other seamlessly.

Remote Procedure Call (RPC)

The Remote Procedure Call (RPC) protocol, also known as function or subroutine call, defines a standard procedure for resource exchange in a client-server model. The client requests functionality or data from the server, which is located in another network or computer, and the server responds accordingly. RPC can be implemented using the SOAP messaging protocol specification.

Service Object Access Protocol (SOAP)

SOAP is a Microsoft-developed protocol specification for exchanging structured data in a distributed environment. SOAP specifies the syntax rules for application requests and responses.

SOAP-compliant APIs allow systems to communicate via Extensible Markup Language (XML), or alternatively, using other protocols like HTTP or Simple Mail Transfer Protocol (SMTP). An important aspect of SOAP is that it has strong security measures built into the specification.

Representational State Transfer (REST)

Developers often find SOAP cumbersome to use as it requires writing lots of code for each task. A simpler alternative is REST, which follows a different logic and makes data available in the form of resources with unique URLs. To request a resource, you just need the URL.

RESTful APIs are web APIs that adhere to REST constraints. They use HTTP requests to interact with resources. While SOAP only supports XML, RESTful systems work with various formats, including HTML, XML, JSON, and plain text.

JavaScript Object Notation (JSON), a lightweight text format, is easy to parse and uses syntax based on Standard ECMA-262. JSON files contain data structures that are compatible with any programming language, with sets of name/value pairs.

API Documentation

API documentation is a deliverable provided together with APIs, which offers instructions for using and integrating with an API. A concise reference manual contains all the information you need to work with an API, providing details about the classes, functions, return types, and arguments. It may also include tutorials and examples.

From the user’s perspective, the API is a tool for quickly integrating resources so they can get on with developing their software. Developer Experience (DX) is the aggregate experience of a developer when they discover, learn to use, and integrate with an API. API documentation is crucial for improving DX.

Here are examples of excellent developer documentation:

• Twilio API documentation—Twilio facilitates communication, offering SDKs in multiple languages and providing sample applications for iOS, Android, and the web. The API documentation uses a three-column format with the code displayed on the right. There are detailed explanations for even the simplest actions, as well as links for further information, and screenshots.
• Spotify for Developers—provides API documentation with demos for basic functions and mock apps, as well as wrappers for various programming languages, and a console for experimentation. The console acts as interactive documentation, letting developers enter data and explore the behavior of endpoints.
• Medium API documentation—the Medium API allows third-party applications to search and post publications on Medium. It is available on GitHub and provides clear and concise instructions with numerous examples. It covers details of all commands, with examples and potential errors. This documentation is reliable but simple, is regularly updated, and lets developers make suggestions directly in GitHub.

Conclusion

In this article I covered several important aspects of APIs:

• • The API economy – widely used by companies of all sizes to buy and sell data and services via APIs.
  • API specifications and protocols – including the legacy RPC protocol, the SOAP protocol developed by Microsoft, and the modern REST protocol.
  • API Documentation – a key part of the developer experience, helping developers understand how to derive value from APIs provided by other companies.

I hope this will be of help as you explore how you can build and make use of API technology.