Application Programming Interface PDF
Application Programming Interface PDF
nent. This specication 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 specication on how to use the mathematical functions included in the math library. Among
In computer programming, an application program- these functions there is a function, named sqrt(), that can
be used to compute the square root of a given number.
ming interface (API) is a set of routines, protocols,
and tools for building software applications. An API The Unix command man 3 sqrt presents the signature of
expresses a software component in terms of its opera- the function sqrt in the form:
tions, inputs, outputs, and underlying types. An API de- SYNOPSIS #include <math.h> double sqrt(double X);
nes functionalities that are independent of their respec- oat sqrtf(oat X); DESCRIPTION sqrt computes the
tive implementations, which allows denitions and im- positive square root of the argument. ... RETURNS
plementations to vary without compromising the inter- On success, the square root is returned. If X is real and
face. A good API makes it easier to develop a program positive...
by providing all the building blocks. A programmer then
puts the blocks together.
This description means that sqrt() function returns the
In addition to accessing databases or computer hardware, square root of a positive oating point number (single or
such as hard disk drives or video cards, an API can ease
double precision), as another oating point number.
the work of programming GUI components. For example, an API can facilitate integration of new features into Hence the API in this case can be interpreted as the colexisting applications (a so-called plug-in API). An API lection of the include les used by a program, written in
can also assist otherwise distinct applications with sharing the C language, to reference that library function, and its
data, which can help to integrate and enhance the func- human readable description provided by the man pages.
tionalities of the applications.
Similarly, other languages have procedural libraries; for
APIs often come in the form of a library that includes example, Perl has dedicated APIs for the same mathespecications for routines, data structures, object classes, matical task with built-in documentation available, which
and variables. In other cases, notably SOAP and REST is accessible using the perldoc utility:
services, an API is simply a specication of remote calls $ perldoc -f sqrt sqrt EXPR sqrt #Return the square root
exposed to the API consumers.[1]
of EXPR. If EXPR is omitted, returns #square root of
An API specication can take many forms, including $_. Only works on non-negative operands, unless #you've
an International Standard, such as POSIX, vendor doc- loaded the standard Math::Complex module.
umentation, such as the Microsoft Windows API, or the
libraries of a programming language, e.g., the Standard
1.2 API in object-oriented languages
Template Library in C++ or the Java APIs.
An API diers from an application binary interface (ABI)
in that an API is source code-based while an ABI is a In its simplest form, an object API is a description of how
binary interface. For instance POSIX is an API, while objects work in a given object-oriented language usually
it is expressed as a set of classes with an associated list of
the Linux Standard Base provides an ABI. [2] [3]
class methods.
1
1.1
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:
Uses
API in procedural languages
USES
System.out.println(Your name is " + name + ".); on a representation that can be saved (serialized) at any
inputScanner.close(); } }
time.[lower-alpha 1]
Similarly the behavior of an object in a concurrent
In the example above, methods nextLine() and close() are (multi-threaded) environment is not necessarily deterpart of the API for the Scanner class, and hence are de- mined by specic methods, belonging to the interface imscribed in the documentation for that API, e.g.:
plemented, but still belongs to the API for that Class of
objects, and should be described in the documentation.
public String nextLine()
[4]
Advances this scanner past the current line and returns
In this sense, in object-oriented languages, the API dethe skipped input...
nes a set of object behaviors, possibly mediated by a set
Returns:
of class methods.
the line that was skipped
In such languages, the API is still distributed as a library.
For example, the Java language libraries include a set of
Throws:
APIs that are provided in the form of the JDK used by the
NoSuchElementException - if no line found
developers to build new Java programs. The JDK includes
the documentation of the API in JavaDoc notation.
IllegalStateException - if this scanner is closed
More generally, in object-oriented languages, an API usually includes a description of a set of class denitions,
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: elds, constants, nested objects, enums, etc.).
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.
3
technology: hence an API for a given language cannot Language Runtime (CLR), and JVM compliant lanbe used in other languages, unless the function calls are guages in the Java Virtual Machine) can share an API.
wrapped with specic adaptation libraries.
In this case, a virtual machine enables language interoperability,
by abstracting a programming language using
To enable the exchange of information among systems
an
intermediate
bytecode and its language bindings. In
that use dierent technologies, when an API implements
these
languages,
the
compiler performs just-in-time coma protocol, it can prescribe a language-neutral message
pilation
or
ahead-of-time
compilation transforming the
format: e.g. SOAP uses XML as a general container for
source
code,
possibly
written
in multiple languages, into
the messages to be exchanged, similarly REST API can
its language-independent bytecode representation.
use both XML and JSON.
For instance, through the bytecode representation, a program written in Groovy or Scala language can use any
1.4.1 Object exchange API and protocols
standard Java class and hence any Java API. This is possible thanks to the fact both Groovy and Scala have an
An object API can prescribe a specic object exchange object model that is a superset of that of the Java lanformat that a program can use locally within an applica- guage; thus, any API exposed via a Java object is accestion, while an object exchange protocol can dene a way sible via Groovy or Scala by an equivalent object invocato transfer the same kind of information in a message sent tion translated in bytecode.
to a remote system.
On the other side, Groovy and Scala introduce rst-class
When a message is exchanged via a protocol between entities that are not present in Java, like closures. These
two dierent platforms using objects on both sides, the entities cannot be natively represented in Java language
object in a programming language can be transformed (Java 8 introduced the concept of lambda expression);
(marshalled and unmarshalled[7] ) in an object in a remote thus, to enable interoperation, a closure is encapsulated
and dierent language: so, e.g., a program written in Java in a standard Java object. In this case the closure invoinvokes a service via SOAP or IIOP written in C# both cation is mediated by a method named call(), which is
programs use APIs for remote invocation (each locally to always present in an closure object as seen by Java, and
the machine where they are working) to (remotely) ex- in Java the closure does not represent a rst-class entity.
change 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 eectively exchanged
2 Web APIs
(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 shar- Main article: Web API
ing technologies like tuple spaces.
1.4.2
1.5
Web APIs are the dened 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 dierent applications
serving dierent types of consumers.[9] When used in
the context of web development, an API is typically dened as a set of Hypertext Transfer Protocol (HTTP) request messages, along with a denition 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).[10]
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.[11]
2.1
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 prole.
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.[12]
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 sucient to utilize
real-world data for decision making.
Implementations
API DESIGN
4 API design
Several principles are commonly used to govern the process of designing APIs. Parnas proposed the concept of
information hiding in 1972. The principle of information
hiding is that one may divide software into modules, each
of which has a specied interface. The interfaces hide the
implementation details of the modules so that users of
modules need not understand the complexities inside the
modules. These interfaces are APIs, and as a result, APIs
should expose only those module details that clients must
know to use modules eectively. Software architecture
is dedicated to creating and maintaining high-level software structureswhich typically includes modules. APIs
reect interfaces between modules. Thus, a system architecture is inextricably related to the APIs that express that
architecture. However, many decisions involved in creating APIs are not architectural, such as naming conventions and many details on how interfaces are structured.
These details of how interfaces are structured, as well
as the software architecture, have signicant impacts on
software quality. For example, Cataldo et al. found that
bugginess is correlated with logical and data dependencies in software.[14] This implies that to reduce bug rates,
software developers should carefully consider API dependencies.
Conways Law states that the structure of a system inevitably reects the structure of the organization that created it. This suggests that to understand how APIs are
designed in the real world, one must also understand the
structures of software engineering organizations. Likewise, an API group should structure itself according to
what the API needs. In a study of 775 Microsoft software engineers, Begel et al. found that in addition to
Microsoft has shown a strong commitment to a backward coordinating regarding API design, software engineers
compatible API, particularly within their Windows API even more commonly coordinate regarding schedules and
(Win32) library, such that older applications may run on features.[15] This reinforces the view that software orga-
5
nizations collaborate extensively and that organizational lution based on an API that becomes deprecated, he/she
structure is important.
might be unable to guarantee the provided service.
Several authors have created recommendations for how
to design APIs, such as Joshua Bloch[16] and Michi
Henning.[17] However, since one of the principles of API 6 API documentation
design is that an API should be consistent with other APIs
already in use in the system, the details of API design are Professional-level documentation[19] for an API should
somewhat language- and system-dependent.
strive to include the following parts:
Release policies
Reference documentation A description of the functions and objects in the API (see the subsection API
reference documentation)
5.1
5.2
API deprecation
6 API DOCUMENTATION
a description of all the data structures it depends An API with unstable parts should document them as unupon
stable.
a description of all the functions signatures, includ- An API with deprecated parts should document them as
deprecated.
ing:
An API that implements a communications protocol
function names
should indicate its general behavior, and should detail:
function parameters names (when it applies)
and types
How to set up a communication session based on
return type for the functions
that protocol, and prerequisites for correctly setting
up a communication session
for each parameter if the parameter is possibly
subjected to modication inside the function
If the communication is stateful or stateless
a description of the handling of any error con In case of stateful sessions: how to handle the state
dition
pre- and post-conditions or invariants
more generally how the state has changed after
the function execution
possible side-eects
any accessibility or visibility constraint.
nested structures, like inner classes or enumerations. An API that interacts with a device should document how
to:
An API in a language using exception handling should re Access the device to extract data from it
port any kind of exception possibly thrown and the specic condition that can cause them to happen.
Modify the state of the device, when possible
An API that can be used in a concurrent environment
Detect error conditions in the device.
should include indications on how its behavior changes
due to possible concurrent access to it: general usability
An API should always indicate, where applicable:
in a concurrent context and possible race conditions.[4]
7
Language version number
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)
API examples
10 See also
API testing
API writer
Calling convention
Comparison of application virtual machines
Common Object Request Broker Architecture
CORBA
12
Document Object Model DOM
Double-chance function
Foreign function interface
Interface control document
List of 3D graphics APIs
Name mangling
Open Service Interface Denitions
Platform-enabled website
Plugin
Software Development Kit
XPCOM
RAML (software)
11
Notes
[1] This is typically true for any class containing simple data
and no link to external resources, like an open connection
to a le, a remote system, or an external device.
12
References
REFERENCES
Google Code.
13
13.1
Application programming interface Source: https://en.wikipedia.org/wiki/Application_programming_interface?oldid=673710319 Contributors: Damian Yerrick, Sodium, Lee Daniel Crocker, CYD, Eloquence, Mav, Uriyan, Bryan Derksen, The Anome, Ed Poor, Andre
Engels, Sfmontyo, Miguel~enwiki, Alan_d, Ellmist, Hfastedge, Frecklefoot, Bdesham, Danja, Michael Hardy, Wapcaplet, Ixfd64, Zeno
Gantner, Skysmith, Mac, Nanshu, JWSchmidt, Mattknox, Andres, Denny, GRAHAMUK, Ehn, Hashar, Jengod, Robneild, Jitse Niesen,
Quux, Tpbradbury, Itai, Bevo, Spikey, Bearcat, Robbot, Chealer, Gak, Mountain, RedWolf, ZimZalaBim, Altenmann, Peak, Hadal, Wikibot, Jleedev, Pengo, David Gerard, Enochlau, Ancheta Wis, Giftlite, JamesMLane, Darklight, Elf, Sj, Kim Bruning, Lupin, Dawidl,
Chameleon, Uzume, Edcolins, Lockeownzj00, Szajd, Cynical, Funvill, Julien~enwiki, Syvanen, Ta bu shi da yu, Slady, Adah1972, Discospinster, Rich Farmbrough, Notinasnaid, Shlomif, Bender235, Limbo socrates, RJHall, CanisRufus, Freakimus, Aude, Diomidis Spinellis, RoyBoy, Bobo192, Smalljim, Redlentil, Enric Naval, Morg~enwiki, Colonoh, Apoltix, K12u, Scott Ritchie, Minghong, Obradovic
Goran, Sam Korn, Chicago god, Anteru, Espoo, Atheken, M5, Zachlipton, AaronL, Poweroid, Diego Moya, Calton, Kocio, InShaneee,
Loshsu, Wtmitchell, Velella, Suruena, Runtime, Pgimeno~enwiki, CloudNine, GeoPurchase, Kbolino, Edwardkerlin, Skeejay, Thryduulf, Rocastelo, Ae-a, Robert K S, Sega381, Blackcats, Ivan007, TrentonLipscomb, Marudubshinki, King of Hearts (old account 2),
SqueakBox, Graham87, Qwertyus, Yurik, DeadlyAssassin, MZMcBride, SMC, Ronocdh, Troymccluresf, Kichik, FlaBot, Riluve, Tijuana
Brass, SteveBaker, Ahunt, Salvatore Ingala, Chobot, Bgwhite, YurikBot, Wavelength, Borgx, NTBot~enwiki, Stephenb, Manop, ENeville,
Heraclius, Dipskinny, Debot~enwiki, Daniduc, JulesH, Davemck, Voidxor, Tony1, Alex43223, Bota47, Jmalin, Plamka, Cedar101, Bryanmonroe, JLaTondre, Teryx, Rwwww, GrinBot~enwiki, SmackBot, Dqpeck, Mihai cartoaje, KnowledgeOfSelf, Unyoyega, Fitch, Eskimbot, Brianski, Ohnoitsjamie, Hmains, Thumperward, DHN-bot~enwiki, Asydwaters, Zhinz, Frap, Addshore, Cybercobra, T-borg, EVula,
Dreadstar, BryanG, Miohtama, Myc2001, Dmh~enwiki, Derek farn, Harryboyles, Jidanni, Mwarf, Soumyasch, Mbeychok, RichMorin,
JHunterJ, SQGibbon, TastyPoutine, MTSbot~enwiki, Phuzion, Pwforaker, Wjejskenewr, Aeternus, Aeons, Courcelles, Jbolden1517,
Atreys, OlegMarchuk, Kickin' Da Speaker, WeggeBot, HenkeB, Old Guard, Neelix, DShantz, Andkore, Yaris678, Michaelas10, ST47,
Farrwill, Pascal.Tesson, Miketwardos, Chiefcoolbreeze, Thijs!bot, Epbr123, Davron, Humu, Muaddeeb, Escarbot, Hires an editor, AntiVandalBot, Seaphoto, Minirogue, MoreThanMike, Avk15gt, Spencer, Deadbeef, JAnDbot, XyBot, Husond, Deepugn, Greensburger,
VoABot II, SHCarter, Tedickey, Torchiest, Hbent, Stephenchou0722, R'n'B, Onixz100, Mange01, Ahzahraee, Jesant13, Drewmeyers,
Looc4s, WTRiker, SlowJog, FrummerThanThou, Raise exception, NewEnglandYankee, Rktur, DeeKay64, DorganBot, Jtowler, Izno,
Innitycomeo, Mpbaumg, Randomalious, SirSandGoblin, VolkovBot, Thisisborin9, Mrh30, JohnBlackburne, Tseay11, Philip Trueman,
TXiKiBoT, Oshwah, Rponamgi, Dschach, Rei-bot, Qxz, Michael Hodgson, Steven J. Anderson, Econterms, Jackfork, Quinet, Daperata, YordanGeorgiev, Legoktm, Renatko, SieBot, John.n-irl, Kernel Saunters, Jerryobject, Bentogoa, Lavers, Nopetro, Aruton, Oxymoron83, SimonTrew, OKBot, Tantrumizer, Loren.wilton, ClueBot, PipepBot, Awg1010, The Thing That Should Not Be, WaltBusterkeys,
Wysprgr2005, Boing! said Zebedee, HUB, Jmclaury, LizardJr8, Dylan620, Liempt, Auntof6, DragonBot, Excirial, Lartoven, Willyos, Rudyray, Sun Creator, Arjayay, Amanuse, Teutonic Tamer, TheresaWilson, BOTarate, Andy16666, Johnuniq, Egmontaz, DumZiBoT, XLinkBot, Kurdo777, Bikingviking, WikHead, Zodon, Airplaneman, Dsimic, Varworld, Pearlls sun, Sakhal, Betterusername, Landon1980, Queenmomcat, Fieldday-sunday, Reemrevnivek, Mac Dreamstate, MrOllie, Download, LaaknorBot, Ginosbot, Tide rolls, Zorrobot, Jarble, Aarsalankhalid, Luckas-bot, Yobot, Ptbotgourou, Fraggle81, Xqt, Scohil, Dmarquard, AnomieBOT, Efa, Piano non troppo,
90, ChristopheS, Materialscientist, Leoholbel, Mquigley8, Chadsmith729, Jpe.pinho, Vkorpor, Foyd, ArthurBot, LilHelpa, Xqbot,
Vikramtheone, Capricorn42, Liorma, TechBot, Rs rams, Ohspite, Boyprose, Utype, Joeldippold, Transpar3nt, Nichobot, RibotBOT, Slurrymaster, IShadowed, Shadowjams, Ebessman, Prari, FrescoBot, Omniscientest, Pepe.agell, Zero Thrust, DivineAlpha, Andremi, Dr Marcus Hill, PaymentVision, Rackspacecloud, Gryllida, Martyn Lovell, Lotje, Dr.mmbuddekar, Consult.kirthi, Edinwiki, Dsnelling, Visvadinu,
AbdulKhaaliq2, Julienj, Jesse V., RjwilmsiBot, 4483APK, Ripchip Bot, Bookiewookie, Andrey86, Dennislees, DASHBot, EmausBot, John
of Reading, Davejohnsan, Coolbloke94, Detnos, Arindra r, Dewritech, Faolin42, TheSoundAndTheFury, Arthur Davies Sikopo, Bhat
sudha, Ashamerie, F, Oulrij, Didym, Bamyers99, Axxonnre, Ocean Shores, Sahimrobot, Steven-arts, Ochado, Status, Thiotimoline,
Mshivaram.ie22, 28bot, ClueBot NG, Kompowiec2, J3st, CocuBot, ClaudiaHetman, Jenova20, Lord Chamberlain, the Renowned, Whitehorse212, Solusinaeternum, Frietjes, SERIEZ, Jakuzem, Widr, Altaf.attari86, Wbm1058, JoeB34, SocialRadiusOly, Griznant, Meldraft,
Qx2020, TCN7JM,
, Whatsnxt, Nsda, Percede, Altar, More4d, Shaun, Softwareqa, Lekshmann, Eric Agbozo, Ulugen, Mogism, Jamesx12345, Sriharsh1234, Snippy the heavily-templated snail, Destroybotter, Pertolepe, C5st4wr6ch, Faizan, Epicgenius, Lsmll,
EagleMongoose, TrOlLLin1212, PublicAmpersand, Blergleblerg, My name is not dave, Jianhui67, RichSaunders, Cornelia Gamst, JaconaFrere, Editorfun, Usarid, Monkbot, Soa Koutsouveli, Nohorbee, Comptly, Tpprufer, Nima1353, Sarasedgewick, Ean Ganaz YK,
Vedanga Kumar, Wolfram graetz, Whereisthesun, KasparBot, Mcoblenz, C a swtest, Distle and Anonymous: 688
13.2
Images
13.3
Content license