A web API is a subset of an application programming interface (API). It is used for exchanging information with a website, either by receiving or by sending data.^[1] A web API typically consists of multiple publicly exposed endpoints that accept HTTP requests and respond with the requested data, typically in the form of JavaScript Object Notation (JSON) or Extensible Markup Language (XML).

Server-side

A server-side web API is a programmatic interface to a defined request-response message system, typically expressed in JSON or XML, which is exposed via the web—most commonly by means of an HTTP-based web server. Mashups are web applications which combine the use of multiple such web APIs.^[2] Webhooks are server-side web APIs that take as input a URI that is designed to be used like a remote named pipe or a type of callback such that the server acts as a client to dereference the provided URI and trigger an event on another server which handles this event thus providing a type of peer-to-peer IPC.

Client-side

A client-side web API is a programmatic interface to extend functionality within a web browser or other HTTP client. Originally these were most commonly in the form of native plug-in architectures however most newer ones target standardized JavaScript bindings.

The Mozilla Foundation created their WebAPI specification which is designed to help replace native mobile applications with HTML5 applications.^[3][4]

Google created their Native Client architecture which is designed to help replace insecure native plug-ins with secure native sandboxed extensions and applications. They have also made this portable by employing a modified LLVM AOT compiler.

Endpoints

Endpoints are one of the most important aspects of interacting with web APIs, as they specify where resources lie that can be accessed by third party software. Usually the access is via a Uniform Resource Identifier (URI) to which HTTP requests are posed, and from which the response is thus expected.

Endpoints need to be static, otherwise the correct functioning of software that interacts with it cannot be guaranteed. If the location of a resource changes (and with it the endpoint) then previously written software will break, as the required resource can no longer be found at the same place. As API providers still want to update their web APIs, many have introduced a versioning system in the URI that points to an endpoint, for example the Clarifai API: The endpoint for the tagging functionality within the web API has the following URI: "https://api.clarifai.com/v1/tag/". The "/v1/" part of the URI specifies access to the first version of the web API. If clarifai decides to update to version two, they can do this while still maintaining support for third party software that uses the first version.^[5]

Examples of Endpoints

• Runscope provides a resource, where various types of endpoints can be tested:^[6] http://httpbin.org/

Example of Interaction with a Web API

Below is an example of interaction with the RESTful Sun Cloud API.^[7]

Request

GET /
 Host: xrgy.cloud.sun.com
 Authorization: Basic xxxxxxxxxxxxxxxxxxx
 Accept: application/vnd.com.sun.cloud.Cloud+json
 X-Compute-Client-Specification-Version: 0.1

REST aims to map CRUD operations (Create, Retrieve, Update, Delete) to types of HTTP requests, namely POST, GET, PUT, and DELETE respectively.^[8] Thus, in the above request, the aim is to retrieve data from the Sun Cloud API, and that is exactly what happens. If the creator of the web API follows the standard, he would not allow creation of data using GET requests and he would also not allow retrieval of data using POST requests. If such standards are followed, that is typically an indicator of a high quality web API.

Response

HTTP/1.1 200 OK
 Content-Type: application/vnd.com.sun.cloud.Cloud+json
 Content-Length: nnn
 
 {
   "implementation_version": "597",
   "vdcs": [
     {
       "name": "XRGY Virtual Data Center",
       "uri": "/vdc"
     }
     {
       "name": "R&D sandbox"
       "uri": "/sandbox"
     }
   ],
   "uri": "http://xrgy.cloud.sun.com/",
   "specification_version": [
     "0.5"
   ]
 }

Aside from the headers, the response contains a JSON object, which can easily be parsed and subsequently be used by any program.

As long as the program is capable of making an HTTP request, it can interact with the Sun Cloud API. If Sun had instead decided to supply its functionalities via SDKs and not via an open web API, API access may be very restricted to certain languages/platforms. In SDK based APIs, the vendor decides which languages/platforms it wants to support and may decide to only support a limited number of languages/platforms. The approach of a web API with public endpoints is much more open and friendly towards languages/platforms that are less widely used.

An important aspect within an interaction with a web API is the consistency of the response. The structure should always be the same. The content may change, but the keys within the JSON object (in this case) generally should not. Thus, in the given example, the key "implementation_version" should always be available for developers to reference, whereas the content "597" may very well change over time.

OAuth

The OAuth logo

Many of the available web APIs heavily rely on user generated content, such as Twitter, Reddit, YouTube, Facebook, etc. To ensure that any program that interacts with any given web API only has access to the resources that individual users of the platform have allowed the third party application to use, OAuth is used. A program requests tokens from an OAuth endpoint of an API and with these tokens, requests can be made for specific resources of any individual user. After the user has given the appropriate permission for the third party application to access, the third party application can make requests to the specific API, for example Twitter, on behalf of the user that has given the relevant permissions.^[9]

More details can be found in the official RFC.

Documentation

Web APIs are an interface for the outside world to interact with the internal business logic. For many companies this internal business logic and the intellectual property associated with it are what distinguishes them from other companies, and potentially what gives them a competitive edge. They do not want this internal information to be exposed. However, in order to provide a web API of high quality, there needs to be a sufficient level of documentation. One API provider that not only provides documentation, but also links to it in its error messages is Twilio.^[10]

Growth of Web APIs

The number of available Web APIs has grown consistently over the past years, as businesses realize the growth opportunities associated with running an open platform, that any developer can interact with. ProgrammableWeb tracks 9000 Web APIs that were available in 2013, up from 105 in 2005.^[11]

Impact and spread of Web APIs

Web APIs have become ubiquitous. There are few major software applications/services that do not offer some form of web API. One of the most common forms of interacting with these web APIs is via embedding external resources, such as tweets, facebook comments, YouTube videos, vines, etc. In fact there are very successful companies, such as disqus, whose main service is to provide embedable tools, such as a feature-rich comment system.^[12] Any website of the TOP 100 Alexa ranked websites uses APIs and/or provides its own APIs, which is a very distinct indicator for the prodigious scale and impact of Web APIs as a whole.^[13]

Business of Web APIs

Commercial

There are a lot of companies, which heavily rely on their API infrastructure to serve their core business clients. In 2014 Netflix received around 5 billion API requests, most of them within their private API.^[14]

Governmental

Many governments collect a lot of data, and some governments are now opening up access to this data. The interfaces through which this data is typically made accessible are web APIs. Web APIs allow for data, such as "budget, public works, crime, legal, and other agency data"^[15] to be accessed by any developer in a convenient manner.

The United States are one of the pioneers in opening up government data for anybody and everybody to use. On its website, data.gov, the following is stated: "Since his first full day in office, President Obama has prioritized making government more open and accountable and has taken substantial steps to increase citizen participation, collaboration, and transparency in government. Data.gov, the central site for U.S. Government data, is an important part of the Administration’s overall effort to open government."^[16]

Web Service (SOAP)

While "web API" is sometimes considered a synonym for web service, Web 2.0 web applications have moved away from SOAP-based web services towards more cohesive collections of RESTful web resources.^[17] These RESTful web APIs are accessible via standard HTTP methods by a variety of HTTP clients including browsers and mobile devices. Additionally, web APIs have the advantage over web services that they are much less difficult to develop. They are also much less resource intensive and usually run faster, since they do not need to perform as many data conversions as required in a SOAP-style API.^[18][19]

This move from web services to web APIs is analogous to the Semantic Web movement towards the Resource Description Framework.^[20]

Industry changes^[19]

• Yahoo provides REST for all their services
• Amazon and eBay provide both REST and SOAP
• Google used to only provide SOAP, but deprecated these resources, in favour of REST in 2006

Popular Web APIs^[21]

• Google Maps
• Twitter
• YouTube
• Flickr
• Facebook
• Amazon Product Advertising
• Twilio
• Last.fm
• eBay

A list of web APIs sorted by popularity can be found here.

Mashups

The term "mashup" describes software that uses two or more resources foreign resources (such as Web APIs) to make up its content.^[22] In the current online environment, there are few websites, which are not part of the "mashup" category. Nearly all news sites have sharing options to Twitter, Facebook, and others and thus make use of their APIs. Mashups combine "components of existing Web sites and applications."^[23]

API modeling languages

A number of modeling languages have been proposed for describing practical web APIs including:

• RESTful API Modeling Language
• Swagger
• API Blueprint
• CloudRail

See also

• HTML5 in mobile devices

References

Further reading

• Jacobson, Daniel; Woods, Dan; Brail, Greg (November 2011). APIs a strategy guide. Sebastopol, Calif: O'Reilly Media. ISBN 978-1-4493-0892-6. 
• Mulloy, Brian. Web API Design - Crafting Interfaces that Developers Love (PDF). apigee.