Content deleted Content added
Citation bot (talk | contribs) m Alter: journal, url, template type, title, pages. Add: year, citeseerx, arxiv, series, doi, pages, volume, isbn, date. Removed accessdate with no specified URL. Removed parameters. Formatted dashes. You can use this bot yourself. Report bugs here. | Headbomb |
|||
Line 22:
API use can vary depending on the type of programming language involved.
An API for a [[procedural programming|procedural language]] such as [[Lua (programming language)|Lua]] could consist primarily of basic routines to execute code, manipulate data or handle errors while an API for an [[object-oriented programming|object-oriented language]], such as Java, would provide a specification of classes and its [[class method]]s.<ref>{{cite journal|last1=de Figueiredo|first1=Luiz Henrique|last2=Ierusalimschy|first2=Roberto|last3=Filho|first3=Waldemar Celes|title=The design and implementation of a language for extending applications|journal=TeCGraf Grupo de Tecnologia
[[Language binding]]s are also APIs. By mapping the features and capabilities of one language to an interface implemented in another language, a language binding allows a library or service written in one language to be used when developing in another language.<ref name=Emery>{{cite web|url=http://www.acm.org/tsc/apis.html|last1=Emery|first1=David|title=Standards, APIs, Interfaces and Bindings|publisher=Acm.org|date=|accessdate=2016-08-08|archive-url=https://web.archive.org/web/20150116081559/http://www.acm.org/tsc/apis.html|archive-date=2015-01-16|dead-url=yes|df=}}</ref> Tools such as [[SWIG]] and F2PY, a [[Fortran]]-to-[[Python (programming language)|Python]] interface generator, facilitate the creation of such interfaces.<ref>{{cite web|url=http://www.f2py.org/ |title=F2PY.org |publisher=F2PY.org |accessdate=2011-12-18}}</ref>
Line 45:
An API can specify the interface between an application and the [[operating system]].<ref name="Oreilly91">{{cite book|last1=Lewine|first1=Donald A.|title=POSIX Programmer's Guide|date=1991|publisher=O'Reilly & Associates, Inc.|page=1|url=ftp://gamma.sbin.org/pub/doc/books/OReilly_-_POSIX_Programmers_Guide.pdf|accessdate=2 August 2016}}{{Dead link|date=November 2018 |bot=InternetArchiveBot |fix-attempted=yes }}</ref> [[POSIX]], for example, specifies a set of common APIs that aim to enable an application written for a POSIX conformant operating system to be [[Compiler|compiled]] for another POSIX conformant operating system.
[[Linux]] and [[Berkeley Software Distribution]] are examples of operating systems that implement the POSIX APIs.<ref name="WestDedrick16">{{cite journal|last1=West|first1=Joel|last2=Dedrick|first2=Jason|title=Open source standardization: the rise of Linux in the network era|journal=Knowledge, Technology & Policy|date=2001|volume=14|issue=2|pages=88–112|url=http://www.joelwest.org/Papers/WestDedrick2001b.pdf|accessdate=2 August 2016
[[Microsoft]] has shown a strong commitment to a backward-compatible API, particularly within its [[Windows API]] (Win32) library, so older applications may run on newer versions of Windows using an executable-specific setting called "Compatibility Mode".<ref>
Line 76:
===Remote APIs===
Remote APIs allow developers to manipulate remote resources through [[Communications protocol|protocol]]s, specific standards for communication that allow different technologies to work together, regardless of language or platform.
For example, the Java Database Connectivity API allows developers to query many different types of [[database]]s with the same set of functions, while the [[Java remote method invocation]] API uses the [[Java Remote Method Protocol]] to allow [[Remote procedure call|invocation]] of functions that operate remotely, but appear local to the developer.<ref name="Bierhoff9">{{cite journal|last1=Bierhoff|first1=Kevin|title=API Protocol Compliance in Object-Oriented Software|journal=CMU Institute for Software Research|date=23 April 2009|url=https://www.cs.cmu.edu/~kbierhof/thesis/bierhoff-thesis.pdf|accessdate=29 July 2016}}</ref><ref name="Wilson16">{{cite web|last1=Wilson|first1=M. Jeff|title=Get smart with proxies and RMI|url=http://www.javaworld.com/javaworld/jw-11-2000/jw-1110-smartproxy.html|website=JavaWorld|accessdate=29 July 2016|date=2000-11-10}}</ref>
Therefore, remote APIs are useful in maintaining the object abstraction in [[object-oriented programming]]; 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.
A modification on the proxy object also will result in a corresponding modification on the remote object.<ref name="AdvancedCorba">{{cite
|first = Michi
|last = Henning
Line 90:
|access-date = 16 June 2015
|year = 1999
|
===Web APIs===
Line 143:
accessdate=2016-02-01}}</ref>
The main policies for releasing an API are:<ref name="Boyd16">{{cite web|last1=Boyd|first1=Mark|title=Private, Partner or Public: Which API Strategy Is Best for Business?|url=http://www.programmableweb.com/news/private-partner-or-public-which-api-strategy-best-business/2014/02/21|website=ProgrammableWeb|accessdate=2 August 2016|date=2014-02-21}}</ref>
*<u>Private</u>: The API is for internal company use only.
Line 150:
===Public API implications===
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.<ref>{{cite
When parts of a publicly presented API are subject to change and thus not stable, such parts of a particular API should be documented explicitly as "unstable". For example, in the [[Google Guava]] library, the parts that are considered unstable, and that might change in the near future, are marked with the [[Java annotation]] <code>@Beta</code>.<ref>{{cite web|url=https://code.google.com/p/guava-libraries/ |title=guava-libraries - Guava: Google Core Libraries for Java 1.6+ - Google Project Hosting
A public API can sometimes declare parts of itself as ''[[Deprecation|deprecated]]'' or rescinded. This usually means that part of the API should be considered a candidate for being removed, or modified in a backward incompatible way. Therefore, these changes allows developers to transition away from parts of the API that will be removed or not supported in the future.<ref name="OracleDeprecation16">{{cite web|last1=Oracle|title=How and When to Deprecate APIs|url=http://docs.oracle.com/javase/7/docs/technotes/guides/javadoc/deprecation/deprecation.html|website=Java SE Documentation|accessdate=2 August 2016}}</ref>
For any library with a significant user base, as soon as an element becomes part of the public API, it starts being used in diverse ways.<ref name="MendezBaudry2013">{{cite
==Documentation==
API documentation describes what services an API offers and how to use those services, aiming to cover everything a client would need to know for practical purposes.
Documentation is crucial for the development and maintenance of applications using the API.<ref name="DekelHerbsleb9">{{cite journal|last1=Dekel|first1=Uri|last2=Herbsleb|first2=James D.|title=Improving API Documentation Usability with Knowledge Pushing|journal=Institute for Software Research, School of Computer Science|date=May 2009|
API documentation is traditionally found in documentation files but can also be found in social media such as blogs, forums, and Q&A websites.<ref name="ParninTreude11">{{cite journal|last1=Parnin|first1=Chris|last2=Treude|first2=Cristoph|date=May 2011|title=Measuring API Documentation on the Web|url=https://www.xmedo.com/measuring-api-documentation-web/|journal=Web2SE|accessdate=22 July 2016}}</ref>
Traditional documentation files are often presented via a documentation system, such as [[Javadoc]] or [[Pydoc]], that has a consistent appearance and structure.
However, the types of content included in the documentation differs from API to API.<ref name="MaalejRobillard12">{{cite journal|last1=Maalej|first1=Waleed|last2=Robillard|first2=Martin P.|title=Patterns of Knowledge in API Reference Documentation|journal=IEEE
In the interest of clarity, API documentation may include a description of classes and methods in the API as well as "typical usage scenarios, code snippets, design rationales, performance discussions, and contracts", but implementation details of the API services themselves are usually omitted.
Restrictions and limitations on how the API can be used are also covered by the documentation. For instance, documentation for an API function could note that its parameters cannot be null, that the function itself is not [[Thread safety|thread safe]],<ref name="MonperrusEichberg11">{{cite journal|last1=Monperrus|first1=Martin|last2=Eichberg|first2=Michael|last3=Tekes|first3=Elif|last4=Mezini|first4=Mira|title=What should developers be aware of? An empirical study on the directives of API documentation|journal=Empirical Software Engineering|date=3 December 2011|volume=17|issue=6|pages=703–737|doi=10.1007/s10664-011-9186-4
Because API documentation tends to be comprehensive, it is a challenge for writers to keep the documentation updated and for users to read it carefully, potentially yielding [[Software bug|bugs]].<ref>{{cite
API documentation can be enriched with [[metadata]] information like [[Java annotation]]s. This metadata can be used by the compiler, tools, and by the ''run-time'' environment to implement custom behaviors or custom handling.<ref>{{cite web|url = http://download.oracle.com/javase/1,5.0/docs/guide/language/annotations.html|title = Annotations|accessdate = 2011-09-30|publisher = [[Sun Microsystems]]}}.</ref>
It is possible to generate API documentation in data-driven manner. By observing a large number of programs that use a given API, it is possible to infer the typical usages, as well the required contracts and directives.<ref>{{Cite
==Copyright controversy==
Line 189:
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.<ref>{{cite news | url=http://www.cnet.com/news/court-sides-with-oracle-over-android-in-java-patent-appeal/ | title=Court sides with Oracle over Android in Java patent appeal | work=CNET | date=May 9, 2014 | accessdate=2014-05-10 | author=Rosenblatt, Seth}}</ref>
In 2016, following a two-week trial, a jury determined that Google's reimplementation of the Java API constituted fair use, but Oracle vowed to appeal the decision.<ref>{{Cite web|url=https://arstechnica.com/tech-policy/2016/05/google-wins-trial-against-oracle-as-jury-finds-android-is-fair-use/|title=Google beats Oracle—Android makes "fair use" of Java APIs|website=Ars Technica|access-date=2016-07-28|date=2016-5-26}}</ref> Oracle won on its appeal, with the [[United States Court of Appeals for the Federal Circuit|Court of Appeals for the Federal Circuit]] ruling that Google's use of the APIs did not qualify for fair use.<ref name="bbn march2018">{{cite web | url = https://www.bloomberg.com/news/articles/2018-03-27/oracle-wins-revival-of-billion-dollar-case-against-google | title = Oracle Wins Revival of Billion-Dollar Case Against Google | first= Susan | last =Decker |date = March 27, 2018 | accessdate = March 27, 2018 | work = [[Bloomberg Businessweek]] }}</ref>
== Examples ==
| |||