The API Opportunity

An API helps to connect colleagues, partners, or third party developers to access data and services to build applications quickly.

Pioneering companies such as Google, Facebook, Apple and Twitter have created wonderful technological solutions to the public using APIs. The use of APIs by these large companies has also helped transform existing businesses and fostered new ideas and industries as well. The success of these ventures is largely by virtue of APIs that link people, their devices and the underlying platforms together. This supports a rich partner ecosystem by enabling developer applications and thereby increasing the sales force.

As the world steps into the era of internet traffic explosion, statistics points towards increased Smartphone sales, improved wireless connectivity and faster internet. This implies a huge shift towards applications and devices. Looking at these trends it is very easy to surmise that APIs will likely power most of the internet traffic in a few years.

An API is like a contract. Once such a contract is in place, developers are enticed to use the API more because the contract increases confidence and reliability. Many people draw parallels to a website while visualizing APIs but an API is quite different from a website.

If you dramatically redesign a website, the only impact is on the user being accustomed to the layout of the content. However, you cannot change the API that way because programs are built on top of it, and programs – unlike humans – are not flexible. If you alter anything in the contract of the API, the potential of its effect upon the apps built is amplified. So, APIs must be treated like software products including the following notions in consideration:

  • Versioning
  • Compatibility
  • Documentation
  • Maintainability
  • Scalability
  • Availability

There are two types of API

  1. Private API
  2. Public API

Private APIs are the more prevalent variety. Popular companies like Facebook and Twitter, make much more extensive use of their own APIs to drive their websites, mobile applications and other products. This use of an API often proves to be more valuable as it supports internal efforts as well as partner relationships – used by staff and by partners with contractual agreements.

Public APIs are available almost to anyone with little or no contractual agreement with the API provider. Often a company starts with a private API and eventually open up some or all of it for public access, probably with some restrictions.


Representation Design

In this post I relate to you how components are represented in REST APIs and outline how to do the in a standard and meaningful way. There four key aspects to consider while thinking about representational design. In each aspect, I have tried to explain the rules that govern what kind of forms and formats are to be used.

1. Message Body Format

REST APIs often employ a text-based format to represent a resource state as a set of meaningful fields. Today, the most commonly used text formats are XML and JSON.

Following are some rules regarding the format of the Message Body

  • Rule: JSON should be supported for resource representation

As a format for data exchange, JSON supports lightweight and simple interoperation:it does its job. Today, JSON is a popular format that is commonly used in REST API design. JSON borrows some of JavaScript’s good parts and benefits from seamless integration with the browser’s native runtime environment.

  • Rule: JSON must be well-formed

A JSON object is an unordered set of name-value pairs. The JSON object syntax defines names as strings, which are always surrounded by double quotes. The following example shows this;


“firstName” : “Osvaldo”,

“lastName” : “Alonso”,

“firstNamePronunciation” : “ahs-VAHL-doe”,

“number” : 6,

“birthDate” : “1985-11-11”


  • Rule: XML and other formats may optionally be used for resource representation

REST APIs may optionally support XML, HTML, and other languages as alternative formats for resource representation.

  • Rule: Additional envelopes must not be created

A REST API must leverage the message “envelope” provided by HTTP. In other words, the body should contain a representation of the resource state, without any additional, transport-oriented wrappers.

2. Hypermedia  Representation

Hypermedia, an extension of the term hypertext, is a nonlinear medium of information which includes graphics, audio, video, plain text and hyperlinks. Hypermedia may be developed a number of ways. Any programming tool can be used to write programs that link data from internal variables and nodes for external data files.

In his thesis, Roy Fielding describes four interface constraints for REST. These are

  1. identification of resources through URIs
  2. manipulation of resources through their representations
  3. self-descriptive representations
  4. hypermedia as the engine of application state.

The rationale behind this fourth constraint is that, by embedding actions controls and URIs within each representation, the client remains independent of the server, and therefore can be universal. The representation that the client receives would include possible new state changes, the URIs and methods that could be used for those transitions, and any associated ordering semantics.

The idea of hypermedia embedding all the action controls necessary to interact with the server works well for an arbitrary number of universal clients interacting with a given server. In this case, the server offering a set of resources specifies all the ordering/interaction rules within the representation.

Most application clients, on the other hand, interact with more than one server, and any given server cannot set the ordering constraints. The clients know how to compose applications out of resources offered by various servers, and each client needs to be able to exercise control over composition. To be able to exercise such a control, client applications cannot be universal, and the benefits that John lists above cannot be completely realized.

  • Rule: A consistent form should be used to represent links
  • Rule: A consistent form should be used to represent link relations
  • Rule: A consistent form should be used to advertise links
  • Rule: A consistent form should be used to represent media type formats

3. Media Type Representation

Programmers working with the Web are familiar with modeling informational in multiple domains and formats a structured representational form, which is carried by an individual HTTP request or response message body, is analogous to an instance of a schema class

  • Rule: A consistent form should be used to represent media type schemas
  1. Document
  2. Class
  3. Storage
  4. Controller
  • Rule: A consistent form should be used to represent media type schemas

4. Error Representation

HTTP’s 4xx and 5xx error status codes should be augmented with client-readable information in the response message’s entity body. The following rules present consistent forms pertaining to errors and error responses.

  • Rule: A consistent form should be used to represent errors
  • Rule: A consistent form should be used to represent error responses

Interaction Design with HTTP

REST APIs embrace all aspects of the HyperText Transfer Protocol, including its request methods, response codes and message headers. HTTP defines methods (sometimes referred to as verbs) to indicate the desired action to be performed on the identified resource. What this resource represents, whether pre-existing data or data that is generated dynamically, depends on the implementation of the server. Often, the resource corresponds to a file or the output of an executable residing on the server.

  • Clients specify the desired interaction method in the Request-Line part of an HTTP request message.

Request-Line = Method SP Request-URI SP HTTP Version CRLF

Each HTTP method has specific, well-defined semantics within the context of a REST API’s resource model. The purpose of GET is to retrieve a representation of a resource’s state. HEAD is used to retrieve the metadata associated with the resource’s state. PUT should be used to add a new resource to a store or update a resource. DELETE removes a resource from its parent. POST should be used to create a new resource within a collection and execute controllers.

These are some of the ground rules relating to HTTP Request Methods:

  • Rule: GET and POST must not be used to tunnel other request methods
    • Tunneling refers to any abuse of HTTP that masks or misrepresents a message’s intent and undermines the protocol’s transparency. A REST API must not compromise its design by misusing HTTP’s request methods in an effort to accommodate clients with limited HTTP vocabulary.
  • Rule: GET must be used to retrieve a representation of a resource
  • Rule: HEAD should be used to retrieve response headers

REST APIs use the Status-Line part of an HTTP response message to inform clients of their request’s overall result.  HTTP defines forty standard status codes that can be used to convey the results of a client’s request. The status codes are divided into the five categories

  1. 1xx: Informational – Communicates transfer protocol-level information.
  2. 2xx: Success – Indicates that the client’s request was accepted successfully.
  3. 3xx: Redirection – Indicates that the client must take some additional action in order to complete their request.
  4. 4xx: Client Error – This category of error status codes points the finger at clients.
  5. 5xx: Server Error – The server takes responsibility for these error status codes.

URI Query Design

A query string is the part of a uniform resource locator (URL) containing data that does not fit conveniently into a hierarchical path structure. The query string commonly includes fields added to a base URI by a Web browser or other client application, for example as part of an HTML form.

Following are the rules relating to the design of URI queries.

  • Rule: The query component of a URI may be used to filter collections or stores

GET /users

GET /users?role=admin

  • Rule: The query component of a URI should be used to paginate collection or store results

GET /users?pageSize=25&pageStartIndex=50

POST /users/search

Parameters: pageSize, pageStartIndex

URI Path Design

Each URI path segment, separated by forward slashes (/), represents a design opportunity. Assigning meaningful values to each path segment helps to clearly communicate the hierarchical structure of a REST API’s resource model design.

  • Rule: A singular noun should be used for document names

  • Rule: A plural noun should be used for collection names

  • Rule: A plural noun should be used for store names

  • Rule: A verb or verb phrase should be used for controller names

  • Rule: Variable path segments may be substituted with identity-based values. The URI template example below has three variables (leagueId,teamId, and playerId):{leagueId}/teams/{teamId}/players/{playerId}