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 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.
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).
API design
Several principles are commonly used to govern the process of designing APIs. Parnas proposed the concept ofinformation hiding in 1972. The principle of information hiding is that one may divide software into modules, each of which has a specified 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 effectively. Software architecture is dedicated to creating and maintaining high-level software structures—which typically includes modules. APIs reflect 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 significant impacts on software quality. For example, Cataldo et al. found that bugginess is correlated with logical and data dependencies in software.This implies that to reduce bug rates, software developers should carefully consider API dependencies.
Conway's Law states that the structure of a system inevitably reflects 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 coordinating regarding API design, software engineers even more commonly coordinate regarding schedules and features. This reinforces the view that software organizations collaborate extensively and that organizational structure is important.
Several authors have created recommendations for how to design APIs, such as Joshua Bloch and Michi Henning.]However, since one of the principles of API design is that an API should be consistent with other APIs already in use in the system, the details of API design are somewhat language- and system-dependent.
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. Changes by a developer to a part of it—for example adding new parameters to a function call—could break compatibility with clients that depend on 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
Reference documentation Professional-level documentation for an API should strive to include the following parts:
- 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 API license
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, and should detail:
- How to set up a communication session based on that protocol, and prerequisites for correctly setting up a communication session
- If the communication is stateful or stateless
- In case of stateful sessions: how to handle the state
- The notation for the kind of messages the protocol can transport
- How the protocol handles communication errors
- If, in case of communication errors, the protocol can resubmit a message
- Security levels supported, and how to secure communication
- Authentication required to set up a session
- If the communication can be associated to a transactional processing, and consequently how to handle transactions
- If the communication can be embedded in an extended conversation, and consequently how to handle the conversation
A graphical API should document:
- Graphical elements it can handle
- How to render graphical elements
- How to lay out elements on the graphical canvas, and how to compose them
- How to interact with graphical elements
- How to handle user input, e.g.,
- How to add callback to specific user events
- How to read information from input fields
An API that interacts with a device should document how to:
- Access the device to extract data from it
- Modify the state of the device, when possible
- Detect error conditions in the device.
An API should always indicate, where applicable:
- Language version number
- Library and other resource dependencies
- Protocol versions it is compatible with or that it implements
- Operating system or platform version it supports
An API that can be used in multiple languages via some form of language inter-operation should document any restrictions to its use by languages other than its native language.
API documentation can be enriched with 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
Main article: Oracle America, Inc. v. Google, Inc.
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:
In 2014, however, Alsup's ruling was overturned on appeal, though 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 testing
- 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
- RAML (software)
No comments:
Post a Comment