Developing APIs‎ > ‎

REST Background

Commonly, you want to provide data access to other computers inside your company, a mobile phone or a partner’s computer. Unfortunately, you cannot easily make a method call (also called a subroutine call, the most basic element of programming), to a different computer in a different language. You need a communication-oriented mechanism to connect these computers together. 

Application Programming Interfaces (APIs) provide this cross-computer, cross-platform connectivity. The Hypertext Transfer Protocol (HTTP) and Representational State Transfer (REST) underlying technologies are core to connecting otherwise disconnected computers. This page explains HTTP, APIs, REST, and how your projects' URLs are constructed.


You may not know it, but you are already familiar with HTTP. Hypertext is text with links and comprises the bulk of the content on the Internet. A protocol is a set of rules that frame interactions in telecommunications. When you submit a URL to your browser, you are making an HTTP GET request, asking for a representation of the data at the URL location to be displayed on your own screen. The view of a web page that you see in your browser is the response to the GET request contained in the URL.

There are other forms of request that can be made in HTTP, including the CRUD functions. All languages understand HTTP. An HTTP call is made up of the following elements:

  • Resource Identifier. Most commonly a URL, Uniform Resource Locator, which is also called a web address. The URL specifies the location of the desired resource.
  • Verb. For example, GET (retrieve data), PUT (alter an existing resource), POST (create a resource) and DELETE.
  • Request/Response. The request is data sent to the server (the data for update), the response is data that is returned (the query result)
  • Header. Comprised of name-value pairs, commonly used for the API Key.
  • Arguments. The values the caller supplies, passed in the URL


An API is the definition of a subroutine/method call: it identifies what parameters you supply and what you get in return. More recently, APIs are presumed to happen over a network, rather than locally. Most often, if a network is involved, the API is of a variety called REST. 


REST is an architectural pattern, a reusable solution to a common occurrence, that uses HTTP. It is language-independent and builds upon the foundations laid by HTTP. REST focuses on resources. A resource is analogous to a table, having a type, data, and relationships to other resources. The resource is identified in the last node of the URL. REST encodes the request response in either XML or JavaScript Object Notation (JSON). JSON is an attractive choice because it is a kind of JavaScript data, and JavaScript is one of the most commonly used languages. Better still, JSON is simple enough to be human readable, and supports nesting.

Nesting allows you to send a request that will return, in one batch, all the subsets of data required by your request, reducing the effects of latency.

The REST Lab is the best way to become familiar with these concepts, giving you a chance to experiment with your own REST server without first writing a program. 

The following screen shot illustrates the anatomy of a REST call: