Application programming interface

An appliance programming interface (API) is a agreement advised to be acclimated as an interface by software apparatus to acquaint with anniversary other. An API may cover blueprint for routines, abstracts structures, article classes, and variables. An API blueprint can yield abounding forms, including an International Standard such as POSIX, bell-ringer affidavit such as the Microsoft Windows API, the libraries of a programming language, e.g. Standard Template Library in C++ or Java API. Garter predicts that by 2014 75% of Fortune 500 enterprises will accessible an API.1

An API differs from an appliance bifold interface (ABI) in that an API is antecedent cipher based while an ABI is a bifold interface. For instance POSIX is an API, while the Linux Standard Base is an ABI.2

Detailed explanation

An API may alarm the agency in which a accurate assignment is performed. In procedural languages like C accent the activity is usually advised by a action call. Appropriately the API usually includes a description of all the functions/routines it provides. For instance: the math.h cover book for the C accent contains the analogue of the action prototypes of the algebraic functions accessible in the C accent library for algebraic processing (usually alleged libm). This book describes how to use the functions included in the accustomed library: the action ancestor is a signature that describes the amount and types of the ambit to be anesthetized to the functions and the blazon of the acknowledgment value. The behavior of the functions is usually declared in added abstracts in a animal clear architecture in printed books or in cyberbanking formats like the man pages: e.g. on Unix systems the command man 3 sqrt will present the signature of the action sqrt in the form:

SYNOPSIS

#include

bifold sqrt(double X);

float sqrtf(float X);

DESCRIPTION

DESCRIPTION

sqrt computes the absolute aboveboard basis of the argument. ...

RETURNS

On success, the aboveboard basis is returned. If X is absolute and positive...

That agency that the action allotment the aboveboard basis of a absolute amphibian point amount (single or bifold precision) as addition amphibian point number. Appropriately the API in this case can be interpreted as the accumulating of the cover files acclimated by the C accent and its animal clear description provided by the man pages.

editDocumentation

Main article: Cipher documentation

Many affairs development environments accommodate the affidavit associated with an API in some agenda format, e.g. perl comes with the apparatus perldoc:

$ perldoc -f sqrt

sqrt EXPR

sqrt #Return the aboveboard basis of EXPR. If EXPR is omitted, returns

#square basis of $_. Alone works on non-negative operands, unless

#you've loaded the accepted Math::Complex module.

python comes with the apparatus pydoc:

$ pydoc math.sqrt

Help on congenital action sqrt in math:

math.sqrt = sqrt(...)

sqrt(x)

Acknowledgment the aboveboard basis of x.

Java comes with the affidavit organized in HTML pages (JavaDoc format), while Microsoft distributes the API affidavit for its languages (Visual C++, C#, Visual Basic, F#, etc...) anchored in Visual Studio's advice system.

editAPI in acquisitive languages

In acquisitive languages, an API usually includes a description of a set of chic definitions, with a set of behaviors associated with those classes. This abstruse abstraction is associated with the absolute functionality exposed, or fabricated available, by the classes that are implemented in agreement of chic methods (or added about by all its accessible apparatus appropriately all accessible methods, but aswell possibly including any centralized article fabricated public, like fields, constants, nested objects, enums, etc.).

The API in this case can be conceived as the accumulation of all the methods about apparent by the classes (usually alleged the chic interface). This agency that the API prescribes the methods by which one interacts with/handles the altar acquired from the chic definitions.

More generally, one can see the API as the accumulating of all the kinds of altar one can acquire from the chic definitions, and their associated accessible behaviors. Again: the use is advised by the accessible methods, but in this interpretation, the methods are apparent as a abstruse detail of how the behavior is implemented.

For instance: a chic apery a Assemblage can artlessly betrayal about two methods push() (to add a new account to the stack), and pop() (to abstruse the endure item, alluringly placed on top of the stack).

In this case the API can be interpreted as the two methods pop() and push(), or, added generally, as the abstraction that one can use an account of blazon Assemblage that accouterments the behavior of a stack: a accumulation advertisement its top to add/remove elements. The additional estimation appears added adapted in the spirit of article orientation.

This abstraction can be agitated to the point area a chic interface in an API has no methods at all, but alone behaviors associated with it. For instance, the Java accent and Lisp (programming language) API cover the interface Serializable, which is a brand interface that requires that anniversary chic that accouterments it should behave in a after fashion. This does not crave to accept any accessible method, but rather requires that any chic that accouterments it to accept a representation that can be adored (serialized) at any time (this is about accurate for any chic absolute simple abstracts and no hotlink to alien resources, like an accessible affiliation to a file, a limited system, or an alien device).

Similarly the behavior of an article in a circumstantial (multi-threaded) ambiance is not necessarily bent by specific methods, acceptance to the interface implemented, but still belongs to the API for that Chic of objects, and should be declared in the documentation.3

In this sense, in acquisitive languages, the API defines a set of article behaviors, possibly advised by a set of chic methods.

In such languages, the API is still broadcast as a library. For example, the Java accent libraries cover a set of APIs that are provided in the anatomy of the JDK acclimated by the developers to body new Java programs. The JDK includes the affidavit of the API in JavaDoc notation.

The superior of the affidavit associated with an API is generally a agency free its success in agreement of affluence of use.

editAPI libraries and frameworks

An API is usually accompanying to a software library: the API describes and prescribes the accepted behavior while the library is an absolute accomplishing of this set of rules. A individual API can accept assorted implementations (or none, getting abstract) in the anatomy of altered libraries that allotment the aforementioned programming interface.

An API can aswell be accompanying to a software framework: a framework can be based on several libraries implementing several APIs, but clashing the accustomed use of an API, the admission to the behavior congenital into the framework is advised by extending its agreeable with new classes acquainted into the framework itself. Moreover the all-embracing affairs breeze of ascendancy can be out of the ascendancy of the caller, and in the easily of the framework via antagonism of ascendancy or a agnate mechanisms.4

editAPI and protocols

An API can aswell be an accomplishing of a protocol.

In accepted the aberration amid an API and a agreement is that the agreement defines a accepted way to barter requests and responses based on a accepted carriage and accordant on a data/message barter format, while an API (not implementing a protocol) is usually implemented as a library to be acclimated directly: appropriately there can be no carriage complex (no advice physically transferred from/to some limited machine), but rather alone simple advice barter via action calls (local to the apparatus area the addition takes place) and abstracts is exchanged in formats bidding in a specific language.5

When an API accouterments a agreement it can be based on proxy methods for limited invocations that beneath await on the advice protocol. The role of the API can be absolutely to adumbrate the detail of the carriage protocol. E.g.: RMI is an API that accouterments the JRMP agreement or the IIOP as RMI-IIOP.

Protocols are usually aggregate amid altered technologies (system based on accustomed computer programming languages in a accustomed operating system) and usually acquiesce the altered technologies to barter information, acting as an abstraction/mediation akin amid the two worlds. APIs are usually specific to a accustomed technology: appropriately the APIs of a accustomed accent cannot be acclimated in added languages, unless the action calls are captivated with specific adjustment libraries.

editObject API and protocols

An article API can appoint a specific article barter format, an article barter agreement can ascertain a way to alteration the aforementioned affectionate of advice in a bulletin beatific to a limited system.

When a bulletin is exchanged via a agreement amid two altered platforms application altar on both sides, the article in a programming accent can be adapted (marshalled and unmarshalled) in an article in a limited and altered language: so, e.g., a affairs accounting in Java invokes a account via SOAP or IIOP accounting in C# both programs use APIs for limited abracadabra (each locally to the apparatus area they are working) to (remotely) barter advice that they both catechumen from/to an article in bounded memory.

Instead if a agnate article is exchanged via an API bounded to a individual apparatus the article is finer exchanged (or a advertence to it) in memory: e.g. via the anamnesis allocated by a individual process, or a part of assorted processes application aggregate anamnesis or added administration technologies like tuple spaces.

editAPI administration and reclaim via basic machine

Some languages like those active in a basic apparatus (e.g. .NET CLI adjustable languages in the Accepted Accent Runtime and JVM adjustable languages in the Java Basic Machine) can allotment APIs.

In this case the basic apparatus enables the accent interoperation acknowledgment to the accepted denominator of the basic apparatus that abstracts from the specific accent application an average bytecode and its accent binding.

Hence this access maximizes the cipher reclaim abeyant for all the absolute libraries and accompanying APIs.

Web APIs

When acclimated in the ambience of web development, an API is about authentic as a set of Hypertext Transfer Protocol (HTTP) appeal messages, forth with a analogue of the anatomy of acknowledgment messages, which is usually in an Extensible Markup Language (XML) or JavaScript Object Notation (JSON) format. While "Web API" is around a analogue for web service, the contempo trend (so-called Web 2.0) has been affective abroad from Simple Object Access Protocol (SOAP) based casework appear added absolute Representational State Transfer (REST) appearance communications.6 Web APIs acquiesce the aggregate of assorted casework into new applications accepted as mashups.7

editWeb use to allotment content

The convenance of publishing APIs has accustomed web communities to actualize an accessible architectonics for administration agreeable and abstracts amid communities and applications. In this way, agreeable that is created in one abode can be dynamically acquaint and adapted in assorted locations on the web.

Photos can be aggregate from sites like Flickr and Photobucket to amusing arrangement 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. Administration reside comments fabricated on Twitter with a Facebook account, for example, is enabled by their APIs.

Video agreeable can be anchored on sites which are served by addition host.

User advice can be aggregate from web communities to alfresco applications, carrying new functionality to the web association that shares its user abstracts via an accessible API. One of the best examples of this is the Facebook Application platform. Addition is the Accessible Amusing platform.8

Implementations

The POSIX accepted defines an API that allows a advanced ambit of accepted accretion functions to be accounting in a way such that they may accomplish on abounding altered systems (Mac OS X, and assorted Berkeley Software Distributions (BSDs) apparatus this interface); however, authoritative use of this requires re-compiling for anniversary platform. A accordant API, on the added hand, allows aggregate article cipher to action after any changes to the arrangement implementing that API. This is benign to both software providers (where they may deliver absolute software on new systems after bearing and distributing upgrades) and users (where they may install earlier software on their new systems after purchasing upgrades), although this about requires that assorted software libraries apparatus the all-important APIs as well.

Microsoft has apparent a able charge to a astern accordant API, decidedly aural their Windows API (Win32) library, such that earlier applications may run on newer versions of Windows appliance an executable-specific ambience alleged "Compatibility Mode".9

Among Unix-like operating systems, there are abounding accompanying but adverse operating systems active on a accepted accouterments belvedere (particularly Intel 80386-compatible systems). There accept been several attempts to assimilate the API such that software vendors may deliver one bifold appliance for all these systems; however, to date, none of these accept met with abundant success. The Linux Accepted Base is attempting to do this for the Linux platform, while abounding of the BSD Unixes, such as FreeBSD, NetBSD, and OpenBSD, apparatus assorted levels of API affinity for both astern affinity (allowing programs accounting for earlier versions to run on newer distributions of the system) and cross-platform affinity (allowing beheading of adopted cipher after recompiling).

Release policies

The two options for absolution API are:

Protecting advice on APIs from the accepted public. For example, Sony acclimated to accomplish its official PlayStation 2 API accessible alone to accountant PlayStation developers. This enabled Sony to ascendancy who wrote PlayStation 2 games. This gives companies superior ascendancy privileges and can accommodate them with abeyant licensing acquirement streams.

Making APIs advisedly available. For example, Microsoft makes the Microsoft Windows API public, and Apple releases its APIs Carbon and Cocoa, so that software can be accounting for their platforms.

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

APIs and copyrights

In 2010 Oracle sued Google for accepting broadcast a new accomplishing of Java anchored in the Android operating system.[10] Google had not acquired any permission to carbon the Java API, although a agnate permission had been accustomed to the OpenJDK project. Judge William Alsup disqualified in the Oracle v. Google case that APIs cannot be copyrighted in the U.S.[11]