REST API

A quick post to explain what a REST API is and how it can be used. I’m clearly making no assumptions about what you know and this is a very brief explanation of a can be very complex topic.

A REST API defines a set of functions which developers can perform requests and receive responses via HTTP protocol such as GET and POST.
Because REST API’s use HTTP, they can be used by practically any programming language and easy to test (it’s a requirement of a REST API that the client and server are independent of each other allowing either to be coded in any language and improved upon supporting longevity and evolution).

The World Wide Web (WWW) is an example of a distributed system that uses REST protocol architecture to provide a hypermedia-driven interface for websites. I’m saying hypermedia (instead of hypertext) as an expansion term to avoid confusion about the REST API supporting other formats to be provided not just HTML.

A Real World Example 

Twitter provides a REST API which you can query to get the latest tweets, you can provide a search query (or hash tag) and it will return the results in JSON format. Example of this HTTP request to the Twitter API to get the latest 3 tweets matching “jQuery”. Try it.

http://search.twitter.com/search.json?q=jQuery&result_type=recent&rpp=3

And to expand on what a REST API should provide:

The REST API should specify what it can provide and how to use it, details such as query parameters, response format, request limitations, public use/API keys, method (GET/POST/PUT/DELETE), language support, callback usage, HTTPS support and resource representations should be self-descriptive…
This is the information provided for the GET search/tweets REST API.


What is REST?

REST stands for Representational state transfer which essentially refers to a style of web architecture that has many underlying characteristics and governs the behavior of clients and servers.

What can use a REST API?

REST API lets you interact with Parse from anything that can send an HTTP request. See Parse REST Definition for examples of this.

REST API’s in the Real World

Welcome the big boys.

The Twitter REST API
Facebook REST API (deprecating)
Google Translate REST API
Flickr REST API
Dropbox REST API
Ebay Developer REST API (product centers)
BING Maps REST API (services)
BING Traffic Incidents API
Magento REST API

What is meant by the term “RESTful API”?

Conforming to the REST constraints is generally referred to as being “RESTful”
An API can be considered “RESTful” if it has the following features (not a complete list just the main ones):

Client–server – The client handles the front end the server handles the backend and can both be replaced independently of each other.

Stateless – No client data is stored on the server between requests and session state is stored on the client.

Cacheable – Clients can cache response (just like browsers caching static elements of a web page) to improve performance.

Complying with these constraints, and thus conforming to the REST architectural style enables any kind of distributed hypermedia system to have desirable emergent properties, such as performance, scalability, simplicity, modifiability, visibility, portability, and reliability. A common trend I have seen is to use absolute urls for RESTful APIs which are meaningful.

Example Dropbox API for file operations


The “RESTful” Client Server Architecture

HTTP, for example, has a very rich vocabulary in terms of verbs (or “methods”), URIs, Internet media types, request and response codes, etc. REST uses these existing features of the HTTP protocol, and thus allows existing layered proxy and gateway components to perform additional functions on the network such as HTTP caching and security enforcement.

RESTful Web Services (API)

A RESTful web service (also called a RESTful web API) is a web service implemented using HTTP and the principles of REST. It is a collection of resources, with four defined aspects:
the base URI for the web service, such as http://example.com/resources/

the Internet media type of the data supported by the web service. This is often XML but can be any other valid Internet media type provided that it is a valid hypertext standard.
the set of operations supported by the web service using HTTP methods (e.g., GET, PUT, POST, or DELETE).

It is a collection of resources, with four defined aspects:

The base URI for the web service, such as http://example.com/resources/

the Internet media type of the data supported by the web service. This is often JSON, XML or YAML but can be any other valid Internet media type.
the set of operations supported by the web service using HTTP methods (e.g., POST, GET, PUT or DELETE).

The API must be hypertext driven.[11]

Popular REST API Request Formats
REST
XML-RPC
SOAP

Also see: The Main Differences Between SOAP and REST APIs

Popular REST API Response Formats

I work mostly with JSON it seems to be the most popular for jQuery developers, for obvious reasons.

REST
XML-RPC
SOAP
JSON
PHP

Do I need an API key to access a REST API?

Most API’s have a request limit and might ask you to provide an API key (which you may have created an application with them). Data sensitive APIs will require you to authenticate and the most popular method is Open Authentication also known as oAuth. I’ve touched briefly on this before on How Twitter oAuth works. Won’t go into oAuth here.

Example is Google Translate requires your API Key in a GET request.

https://www.googleapis.com/language/translate/v2?key=INSERT-YOUR-KEY&source=en&target=de&q=Hello%20world

So is it a REST API or just an API?

Well to decide this you will have to stufy the documentation and determine if the API satisfies the criterion to qualify it to be RESTful. The Atom API is a good example of one that truely qualifies it to be RESTful.