Everyone who came somehow across software development has probably heard this term. But not everyone understands what exactly it means and why it is needed. In this article, we will consider what an API is, where, how, and why it is used. We will also look at the types and specifications of APIs and how it can simplify the life of a web programmer.

What is an API?

The abbreviation API stands for Application Programming Interface. Most large companies develop APIs for customers or for internal use at some point. This is an application programming interface that allows services to interact, access, and share data. In essence, an API acts as an intermediary between two applications or services; it provides tools (classes, functions, structures) implemented in one service, and creates an environment for building applications. You can have a look at an API catalogue here.

An example of the API that is familiar to most Internet users is the sign-up with a social network account. Thanks to the API, the site can connect to the database of the social network and get the information it needs.

If you want to know what technologies and APIs different sites and applications use, you can check it on Stackshare.

What are the kinds of APIs?

APIs can be classified according to the availability/release policies for which they are designed.

  • Private APIs are solely used within an organization. Apps are mostly built for company employees. Common use cases are the integration of company systems/apps or the development of new systems using existing resources.
  • Partner APIs are openly promoted but available for known business partners. End customers or business users are the potential target audience for such apps. Software integration between two organizations is a popular use case for these APIs.
  • Public or external APIs are available to any third-party developers. Apps with public APIs are mostly designed for end customers. The API release policy usually allows for increasing brand awareness and fostering external innovation. Public APIs can be open and commercial.

In terms of use cases, APIs can be named after the system for which they are designed.

#1. Database APIs

If a developer wants an application to tap into a particular database, using an API would be the ideal way to accomplish this. For instance, The Drupal 7 Database API makes possible writing the same requests for proprietary and open source databases (MySQL, Oracle, MSSQL, and so on). 

ORDS Database API is a database management and monitoring REST API built into Oracle REST Data Services. Depending on the version and configuration, ORDS database API provides services such as pluggable database management, data export, and database performance analysis. 

#2. Operating systems APIs

Almost all operating systems (UNIX, Windows, OS X, etc.) have an API, using which programmers can create applications for this operating system. The main function of operating systems APIs is dealing with a lot of system calls. In the software industry, the APIs for standard functionality are of great importance, as they ensure that all programs using the common API will work equally well, or at least in a typical way. In the case of GUI APIs, this means that the programs will have a similar user interface, which facilitates the process of mastering new software products.

An example of an operating system API is Cocoa. It is Apple’s native object-oriented application programming interface for macOS, its desktop operating system. For end-users, Cocoa applications are those written using the Cocoa programming environment. Such applications usually have a familiar look and feel, since the Cocoa programming environment automates many development aspects.

#3. Remote APIs

If an API is used for the interaction between apps working on different machines, it is named a remote API. Such kind of API defines communication standards of remotely located applications. One app requests access to the other one that is placed outside the device, hence the name. As nowadays the most widely used communication network is the internet, most remote APIs are based on web standards. Here are two common API examples, Java Database Connectivity API and Java Remote Method Invocation API.

#4. Web APIs

This web development concept describes software that enables “communication” between a web app and a server using Hypertext Transfer Protocol (HTTP). On the server-side, a web API is a request-response message system, often expressed in JSON or XML. On the client-side, an API serves to enhance the capabilities within a web browser or an HTTP client. 

Web APIs are used to extend the features of applications and sites. For instance, YouTube API allows for embedding YouTube videos into your site. Twitter API lets you to add features, such as showing the latest tweets on the site.

What are API Protocols and Standards?

The API specifications explain how it functions and what to expect from this product. At the same time, it is a set of standards that facilitate data exchange. The most common APIs on the World Wide Web are the so-called Web APIs, which are used as a platform for creating HTTP services. Among them, there are:

RPC (Remote Procedure Call) 

This group includes technologies that allow applications to interact at a distance. This means that one program can call some method in another program, which can be run on a computer located in another city or even country. 

For example, CORBA technologies and Java RMI are developed on the basis of RPC.

SOAP (Simple Object Access Protocol) 

The SOAP protocol was created in 1998 by Dave Winer’s development team. He worked at Microsoft and Userland but was then transferred to the W3C consortium.

SOAP does not distinguish between a procedure call and a response to it, but simply defines the message format in the form of an XML document. A message may contain a procedure call, an answer to it, a request to perform some other actions, or just text. 

The SOAP specification is not interested in the contents of the message; it only defines its design. SOAP is based on the XML language and extends some application-level protocol —HTTP, FTP, SMTP, etc. Typically, HTTP is most commonly used. Instead of using HTTP to request the HTML page that will be displayed in the browser, SOAP sends an XML message through the HTTP request and receives the result in an HTTP response.

REST (Representational State Transfer)

REST is a set of principles that define how Web standards, such as HTTP and URIs, are supposed to be used. It is not a protocol or standard, but an architectural style. Key principles of REST are: 

  • Client-server model. A network architecture in which network load or jobs are distributed between service providers (called servers) and service customers (called clients).
  • Statelessness. The server should not store any client information.
  • Standardized interface. Generally accepted technologies and techniques are used to work with resources.

Key principles of interaction in REST are:

  • Data sources are called resources. Each resource has a global identifier. 
  • The client receives data representation when contacting. 
  • The information contained in the request must be sufficient to process the request itself (self-descriptive messages).
  • XML, HTML, JSON can be used to represent the returned information.

GraphQL

GraphQL is a syntax that describes how to request data and is mainly used by the client to download data from the server. GraphQL has three main characteristics. It allows the client to specify what data they need; it facilitates aggregation of data from multiple sources; it uses a type system to describe data.

How is an API regulated?

API documentation is technical documentation that records instructions on how to use the API effectively. For actively developing products, supporting API documentation plays an important role, but do not forget about the relevance of this data. API documentation not only records the necessary information in a document but also maintains its relevance.

For instance, we take an employee to create API documentation. He/she will distribute this documentation in the form of files or publish it on the site. This approach works well but has a number of significant drawbacks, such as the human factor and the rapid obsolescence of documentation. A person can forget something, write incorrectly, whatever. Once the code has changed, the documentation is out of date.

To simplify the documentation process, you can use specialized tools and services. Typically, they generate documentation based on the description in some standardized format — usually JSON or Markdown. As an alternative, you can try Apiary. For instance, we used this service to describe our project management tool, Hygger.

Takeaways

The main advantage of working with the API is saving time when developing your own services. Programmers get ready-made solutions and don’t need to reinvent the wheel. At the same time, this system is not perfect. The API is intended primarily for general use; it may not be suitable for creating some special functionality.