API

"API" redirects here. For other uses, see API (disambiguation).

In computer programming, an application programming interface (API) is a set of routines, protocols, and tools for building software applications. An API expresses a software component in terms of its operations, inputs, outputs, and underlying types. An API defines functionalities that are independent of their respective implementations, which allows definitions and implementations to vary without compromising each other. A good API makes it easier to develop a program by providing all the building blocks. A programmer then puts the blocks together.

In addition to accessing databases or computer hardware, such as hard disk drives or video cards, an API can ease the work of programming GUI components. For example, an API can facilitate integration of new features into existing applications (a so-called "plug-in API"). An API can also assist otherwise distinct applications with sharing data, which can help to integrate and enhance the functionalities of the applications.

APIs often come in the form of a library that includes specifications for routines, data structures, object classes, and variables. In other cases, notably SOAP and REST services, an API is simply a specification of remote calls exposed to the API consumers.

An API specification can take many forms, including an International Standard, such as POSIX, vendor documentation, such as the Microsoft Windows API, or the libraries of a programming language, e.g., the Standard Template Library in C++ or the Java APIs.

An API differs from an application binary interface (ABI) in that an API is source code-based while an ABI is a binary interface. For instance POSIX is an API, while the Linux Standard Base provides an ABI.

Uses

API in procedural languages

In most procedural languages, an API specifies a set of functions or routines that accomplish a specific task or are allowed to interact with a specific software component. This specification is presented in a human readable format in paper books or in electronic formats like eBooks or as man pages. For example, the math API on Unix systems is a specification on how to use the mathematical functions included in the math library. Among these functions there is a function, named sqrt(), that can be used to compute the square root of a given number.

The Unix command man 3 sqrt presents the signature of the function sqrt in the form:

SYNOPSIS
            #include <math.h>
            double sqrt(double X);
            float  sqrtf(float X);
DESCRIPTION
       sqrt computes the positive square root of the argument. ...
RETURNS
       On success, the square root is returned. If X is real and positive...

This description means that sqrt() function returns the square root of a positive floating point number (single or double precision), as another floating point number.

Hence the API in this case can be interpreted as the collection of the include files used by a program, written in the C language, to reference that library function, and its human readable description provided by the man pages.

Similarly, other languages have procedural libraries; for example, Perl has dedicated APIs for the same mathematical task with built-in documentation available, which is accessible using the perldoc utility:

$ perldoc -f sqrt
       sqrt EXPR
       sqrt    #Return the square root of EXPR.  If EXPR is omitted, returns
               #square root of $_.  Only works on non-negative operands, unless
               #you've loaded the standard Math::Complex module.

API in object-oriented languages

In its simplest form, an object API is a description of how objects work in a given object-oriented language – usually it is expressed as a set of classes with an associated list of class methods.

For example, in the Java language, if the class Scanner is to be used (a class that reads input from the user in text-based programs), it is required to import the java.util.Scanner library, so objects of type Scanner can be used by invoking some of the class' methods:

import java.util.Scanner;

public class Test {
   public static void main(String[] args) {
       System.out.println("Enter your name:");
       Scanner inputScanner = new Scanner(System.in);
       String name = inputScanner.nextLine();
       System.out.println("Your name is " + name + ".");
       inputScanner.close();
  }
}

In the example above, methods nextLine() and close() are part of the API for the Scanner class, and hence are described in the documentation for that API, e.g.:

public String nextLine()

Advances this scanner past the current line and returns the input that was skipped. ...

Returns:

the line that was skipped

Throws:

NoSuchElementException - if no line was found

IllegalStateException - if this scanner is closed

More generally, in object-oriented languages, an API usually includes a description of a set of class definitions, with a set of behaviors associated with those classes. This abstract concept is associated with the real functionality exposed, or made available, by the classes that are implemented in terms of class methods (or more generally by all its public components hence all public methods, but also possibly including any internal entity made public like: fields, constants, nested objects, enums, etc.).

The API in this case can be conceived of as the totality of all the methods publicly exposed by the classes (usually called the class interface). This means that the API prescribes the methods by which one interacts with/handles the objects derived from the class definitions.

More generally, one can see the API as the collection of all the kinds of objects one can derive from the class definitions, and their associated possible behaviors. Again: the use is mediated by the public methods, but in this interpretation, the methods are seen as a technical detail of how the behavior is implemented.

For instance: a class representing a Stack can simply expose publicly two methods push() (to add a new item to the stack), and pop() (to extract the last item, ideally placed on top of the stack).

In this case the API can be interpreted as the two methods pop() and push(), or, more generally, as the idea that one can use an item of type Stack that implements the behavior of a stack: a pile exposing its top to add/remove elements. The second interpretation appears more appropriate in the spirit of object orientation.

This concept can be carried to the point where a class interface in an API has no methods at all, but only behaviors associated with it. For instance, the Java and Lisp language APIs include the interface named Serializable, which is a marker interface that requires each class implementing it to behave in a serialized fashion. This does not require implementation of a public method, but rather requires any class which implements this interface to be based on a representation that can be saved (serialized) at any time.

Similarly the behavior of an object in a concurrent (multi-threaded) environment is not necessarily determined by specific methods, belonging to the interface implemented, but still belongs to the API for that Class of objects, and should be described in the documentation.

In this sense, in object-oriented languages, the API defines a set of object behaviors, possibly mediated by a set of class methods.

In such languages, the API is still distributed as a library. For example, the Java language libraries include a set of APIs that are provided in the form of the JDK used by the developers to build new Java programs. The JDK includes the documentation of the API in JavaDoc notation.

The quality of the documentation associated with an API is often a factor determining its success in terms of ease of use.

API libraries and frameworks

An API is usually related to a software library: the API describes and prescribes the expected behavior while the library is an actual implementation of this set of rules. A single API can have multiple implementation (or none, being abstract) in the form of different libraries that share the same programming interface.

An API can also be related to a software framework: a framework can be based on several libraries implementing several APIs, but unlike the normal use of an API, the access to the behavior built into the framework is mediated by extending its content with new classes plugged into the framework itself. Moreover the overall program flow of control can be out of the control of the caller, and in the hands of the framework via inversion of control or a similar mechanism.

API and protocols

An API can also be an implementation of a protocol.

When an API implements a protocol it can be based on proxy methods for remote invocations that underneath rely on the communication protocol. The role of the API can be exactly to hide the detail of the transport protocol. E.g.: RMI is an API that implements the JRMP protocol or the IIOP as RMI-IIOP.

Protocols are usually shared between different technologies (system based on given computer programming languages in a given operating system) and usually allow the different technologies to exchange information, acting as an abstraction/mediation level between the two different environments. APIs are usually specific to a given technology: hence the APIs of a given language cannot be used in other languages, unless the function calls are wrapped with specific adaptation libraries.

To enable the exchange of information among systems that use different technologies, when an API implements a protocol, it can prescribe a language-neutral message format: e.g. SOAP uses XML as a general container for the messages to be exchanged.

Object exchange API and protocols

An object API can prescribe a specific object exchange format which is usable locally within an application, while an object exchange protocol can define a way to transfer the same kind of information in a message sent to a remote system.

When a message is exchanged via a protocol between two different platforms using objects on both sides, the object in a programming language can be transformed (marshalled and unmarshalled) in an object in a remote and different language: so, e.g., a program written in Java invokes a service via SOAP or IIOP written in C# both programs use APIs for remote invocation (each locally to the machine where they are working) to (remotely) exchange information that they both convert from/to an object in local memory.

Instead when a similar object is exchanged via an API local to a single machine the object is effectively exchanged (or a reference to it) in memory: e.g. via memory allocated by a single process, or among multiple processes using shared memory, an application server, or other sharing technologies like tuple spaces.

Object remoting API and protocols

An object remoting API is based on a remoting protocol, such as CORBA, that allows remote object method invocation. A method call, executed locally on a proxy object, invokes the corresponding method on the remote object, using the remoting protocol, and acquires the result to be used locally as return value.

When remoting is in place, a modification on the proxy object corresponds to a modification on the remote object. When only an object transfer takes place, the modification to the local copy of the object is not reflected on the original object, unless the object is sent back to the sending system.

API sharing and reuse via virtual machine

Some languages like those running in a virtual machine (e.g. .NET CLI compliant languages in the Common Language Runtime (CLR), and JVM compliant languages in the Java Virtual Machine) can share an API. In this case, a virtual machine enables language interoperability, by abstracting a programming language using an intermediate bytecode and its language bindings. In these languages, the compiler performs just-in-time compilation or ahead-of-time compilation transforming the source code, possibly written in multiple languages, into its language-independent bytecode representation.

For instance, through the bytecode representation, a program written in Groovy or Scala language can use any standard Java class and hence any Java API. This is possible thanks to the fact both Groovy and Scala have an object model that is a superset of that of the Java language; thus, any API exposed via a Java object is accessible via Groovy or Scala by an equivalent object invocation translated in bytecode.

On the other side, Groovy and Scala introduce first-class entities that are not present in Java, like closures. These entities cannot be natively represented in Java language (Java 8 introduced the concept of lambda expression); thus, in order to enable interoperation a closure is encapsulated in a standard Java object. In this case the closure invocation is mediated by a method named call() which is always present in an closure object as seen by Java, and in Java the Closure does not represent a first-class entity.

Web APIs

Main article: Web API

Web APIs are the defined interfaces through which interactions happen between an enterprise and applications that use its assets. An API approach is an architectural approach that revolves around providing programmable interfaces to a set of services to different applications serving different types of consumers. When used in the context of web development, an API is typically defined as a set of Hypertext Transfer Protocol (HTTP) request messages, along with a definition of the structure of response messages, which is usually in an Extensible Markup Language (XML) or JavaScript Object Notation (JSON) format. While "web API" historically has been virtually synonymous for web service, the recent trend (so-called Web 2.0) has been moving away from Simple Object Access Protocol (SOAP) based web services and service-oriented architecture (SOA) towards more direct representational state transfer (REST) style web resources and resource-oriented architecture (ROA). Part of this trend is related to the Semantic Web movement toward Resource Description Framework (RDF), a concept to promote web-based ontology engineering technologies. Web APIs allow the combination of multiple APIs into new applications known as mashups.

Web use to share content

The practice of publishing APIs has allowed web communities to create an open architecture for sharing content and data between communities and applications. In this way, content that is created in one place can be dynamically posted and updated in multiple locations on the web:

• Photos can be shared from sites like Flickr and Photobucket to social network sites like Facebook and MySpace.
• Content can be embedded, e.g. embedding a presentation from SlideShare on a LinkedIn profile.
• Content can be dynamically posted. Sharing live comments made on Twitter with a Facebook account, for example, is enabled by their APIs.
• Video content can be embedded on sites served by another host.
• User information can be shared from web communities to outside applications, delivering new functionality to the web community that shares its user data via an open API. One of the best examples of this is the Facebook Application platform. Another is the Open Social platform.
• If content is a direct representation of the physical world (e.g., temperature at a geospatial location on earth) then an API can be considered an "Environmental Programming Interface" (EPI). EPIs are characterized by their ability to provide a means for universally sequencing events sufficient to utilize real-world data for decision making.

Implementations

The POSIX standard defines an API that allows writing a wide range of common computing functions in a way such that they can operate on many different systems (Mac OS X, and various Berkeley Software Distributions (BSDs) implement this interface). However, using this requires re-compiling for each platform. A compatible API, on the other hand, allows compiled object code to function with no changes to the system that implements that API. This is beneficial to both software providers (where they may distribute existing software on new systems without producing and →distributing upgrades) and users (where they may install older software on their new systems without purchasing upgrades), although this generally requires that various software libraries implement the necessary APIs as well.

Microsoft has shown a strong commitment to a backward compatible API, particularly within their Windows API (Win32) library, such that older applications may run on newer versions of Windows using an executable-specific setting called "Compatibility Mode".

Among Unix-like operating systems, there are many related but incompatible operating systems running on a common hardware platform (particularly Intel 80386-compatible systems). There have been several attempts to standardize the API such that software vendors may distribute one binary application for all these systems; however, to date, none of these has met with much success. The Linux Standard Base is attempting to do this for the Linux platform, while many of the BSD Unixes, such as FreeBSD, NetBSD, and OpenBSD, implement various levels of API compatibility for both backward compatibility (allowing programs written for older versions to run on newer distributions of the system) and cross-platform compatibility (allowing execution of foreign code without recompiling).

Release policies

The main policies for releasing an API are:

• Protecting information on APIs from the general public. For example, Sony used to make its official PlayStation 2 API available only to licensed PlayStation developers. This enabled Sony to control who wrote PlayStation 2 games. This gives companies quality control privileges and can provide them with potential licensing revenue streams.
• Making APIs freely available. For example, Microsoft makes the Microsoft Windows API public, and Apple releases its APIs Carbon and Cocoa, so that software can be written for their platforms.

A mix of the two behaviors can be used as well.

Public API implications

An API can be developed for a restricted group of users, or it can be released to the public.

An important factor when an API becomes public is its interface stability: if the developer of an API changes a part of it, for example by adding new parameters to some function calls, it could break the compatibility with all clients that depend on or use that API.

When parts of a publicly presented API are subject to change and thus not stable, such parts of a particular API should be explicitly documented as unstable. For example, in the Google Guava library the parts that are considered unstable, and that might change in a near future, are marked with the Java annotation @Beta.

API deprecation

A public API can sometimes declare parts of itself as deprecated. This usually means that such part of an API should be considered candidated for being removed, or modified in a backward incompatible way.

When adopting a third-party public API, developers should consider the deprecation policy used by the producer of that API; if a developer publicly releases a solution based on an API that becomes deprecated, he/she might be unable to guarantee the provided service.

API documentation

Professional-level documentation for an API should strive to include the following parts:

Reference documentation

A description of the functions and objects in the API (see the subsection API reference documentation)

Overview and concepts

A narrative description of the different parts of the API and how they interact. Major frameworks in the API, such as its GUI, network, and file system frameworks should have their own separate section.

Tutorials/training classes

Step-by-step instructions that show developers how to accomplish a particular task. The text should include code that developers can copy into their own applications. For example, a training class for a cryptographic API would include code that shows developers how to use the API to encrypt a file.

Installation/getting started/troubleshooting documentation

One or more documents that show developers how to do the following:

• Obtain the software development kit (SDK) for the API
• Install the SDK on a development machine
• Obtain keys, accounts, and so forth that allow access
• Deploy or provide client libraries
• Troubleshoot problems with using the SDK

SDK tools documentation

Documents that describe how to install and use build, compile, and deploy tools

License information

Documents that describe the licenses under which the API is provided

API reference documentation

The reference documentation for an API is an intrinsic part of any API, and without it the API is unusable. Every aspect of the API, no matter how trivial, should be stated explicitly.

When an API documents a library of functions in a procedural language it should include:

• a description of all the data structures it depends upon
• a description of all the functions signatures, including:
  • function names
  • function parameters names (when it applies) and types
  • return type for the functions
  • for each parameter if the parameter is possibly subjected to modification inside the function
  • a description of the handling of any error condition
  • pre- and post-conditions or invariants
  • more generally how the state has changed after the function execution
  • possible side-effects
• any accessibility or visbility constraint.

An object API should document:

• the relationship of any type to other types: inheritance (super-types, sub-types, implemented interfaces or traits), composite structures, delegating entities or any mixed-in set of functionality
• the public part of an object derived from a class definition, hence:
  • its public constants
  • the name and type of the member variables (fields or properties) that are directly accessible for any object
  • the signature of the class methods including information similar to that for functions in procedural languages, possibly including a list of getter and setter methods used to access or modify encapsulated information
  • any class-specific operators, in case the language supports operator overloading
  • indication whether the fields or methods have a static nature
• any constraint that applies to the objects one can create
• nested structures, like inner classes or enumerations.

An API in a language using exception handling should report any kind of exception possibly thrown and the specific condition that can cause them to happen.

An API that can be used in a concurrent environment should include indications on how its behavior changes due to possible concurrent access to it: general usability in a concurrent context and possible race conditions.

An API with unstable parts should document them as unstable.

An API with deprecated parts should document them as deprecated.

An API that implements a communications protocol should indicate its general behavior, which should includes details on:

• how to set up a communication session based on that protocol and prerequisites for a correct setup of the communication session
• if the communication is stateful or stateless
• in case of state-full sessions: how the state is handled
• the notation for the kind of messages that the protocol can transport
• how communication errors are handled
• if, in case of communication errors, a message resubmission can happen
• the security levels supported, and how to secure the communication
• any authentication required to set up the communication session
• if the communication can be associated to a transactional processing, and consequently how to handle the transactions
• if the communication can be embedded in an extended conversation, and consequently how to handle the conversation.

A graphical API should document:

• the kind of graphical elements that can be handled
• how to render the graphical elements
• how to lay out the elements on the graphical canvas, and how to compose them
• how to interact with the graphical elements
• how to handle the user inputs, e.g.:
  • how to add callback to specific user events,
  • or how to read information from input fields...

An API used to interact with a device should document the interaction with it an hence:

• how to access the device to extract data from it
• how to modify the state of the device, when possible
• how to detect error conditions in the device.

An API should always indicate where it applies to: version number of the language, library, and of any other resource it depends upon, the version of the protocols it is compatible with or that it implements, if any, and the version of the operative system or platform it supports.

An API that can be used in multiple languages via some form of language inter-operation should document any restrictions to its usage in case of usage from different languages from its native language bhavesh.

API documentation can be enriched using metadata information: like Java annotation, or CLI metadata. This metadata can be used by the compiler, tools, and by the run-time environment to implement custom behaviors or custom handling.

APIs and copyrights

In 2010, Oracle sued Google for having distributed a new implementation of Java embedded in the Android operating system. Google had not acquired any permission to reproduce the Java API, although a similar permission had been given to the OpenJDK project. Judge William Alsup ruled in the Oracle v. Google case that APIs cannot be copyrighted in the U.S, and that a victory for Oracle would have widely expanded copyright protection and allowed the copyrighting of simple software commands:

To accept Oracle's claim would be to allow anyone to copyright one version of code to carry out a system of commands and thereby bar all others from writing their own different versions to carry out all or part of the same commands.

In 2014, however, Alsup's ruling was overturned on appeal, although the question of whether such use of APIs constitutes fair use was left unresolved.

2013 saw the creation of the "API Commons" initiative. API Commons is a common place to publish and share your own API specifications and data models in any format such as Swagger, API Blueprint or RAML, as well as to explore and discover the API designs of others. The API specifications and data models declared in API Commons are available publicly under the Creative Commons license.

API examples

See also: Category:Application programming interfaces

• ASPI for SCSI device interfacing
• Cocoa and Carbon for the Macintosh
• DirectX for Microsoft Windows
• EHLLAPI
• Java APIs
• ODBC for Microsoft Windows
• OpenAL cross-platform sound API
• OpenCL cross-platform API for general-purpose computing for CPUs & GPUs
• OpenGL cross-platform graphics API
• OpenMP API that supports multi-platform shared memory multiprocessing programming in C, C++ and Fortran on many architectures, including Unix and Microsoft Windows platforms.
• Server Application Programming Interface (SAPI)
• Simple DirectMedia Layer (SDL)

Language bindings and interface generators

APIs that are intended to be used by more than one high-level programming language often provide, or are augmented with, facilities to automatically map the API to features (syntactic or semantic) that are more natural in those languages. This is known as language binding, and is itself an API. The aim is to encapsulate most of the required functionality of the API, leaving a "thin" layer appropriate to each language.

Below are listed some interface generator tools that bind languages to APIs at compile time:

• SWIG – an open-source interfaces bindings generator supporting numerous programming languages
• F2PY – a Fortran to Python interface generator

See also

• API writer
• Calling convention
• Comparison of application virtual machines
• Common Object Request Broker Architecture CORBA
• Document Object Model DOM
• Double-chance function
• Foreign function interface
• Interface control document
• List of 3D graphics APIs
• Name mangling
• Open Service Interface Definitions
• Platform-enabled website
• Plugin
• Software Development Kit
• XPCOM

External links

• What is an API?
• How to design a good API and why it matters
• How to Write an API
• Architecture of API