REST API

REST (Representational State Transfer) is an architectural style for APIs. It takes advantage of existing protocols to transfer information from a client to a server, then receives a response back from the server. While REST APIs can be used over almost any protocol, web APIs such as Revel's API use HTTP. This means that developers do not need to install additional libraries or software to get started with a REST API.

The representation of this state is usually in JSON, though it can be in XML or HTML. The Revel API returns responses in JSON.

What You Need to Know

Before we dive in, there are a few key terms you need to know:

Client - This is you, the person or software using the API. You can call the API via a script, a web browser, a mobile app, or via any other program you write.

Resource - A resource is any object the API can provide information about. For Revel's API, this can mean a product, an order, an employee, or more. Each resource has a unique identifier, such as a name or a number.

Endpoint - The URL for the resource you are interested in.

Request - A message sent to the server requesting information. This message is sent from

Server - The receiver of the information you're requesting. This is typically another computer.

Response - The information the client receives from the server regarding a request. Revel's API returns this response in JSON, although other APIs may return this information in XML or HTML.

Types of HTTP methods or operations

Each API request uses an HTTP method to indicate the desired action on the resource. Revel's API can use one of five HTTP methods, described in the table below.

Properties of a RESTful API

A RESTful API satisfies these six properties:

• Uniform interface
• Client-server separation
• Stateless
• Layered system
• Cacheable
• Code-on-demand (optional)

What do these mean? Let's take a look.

Uniform interface

A uniform interface is a fundamental aspect to any REST API's design. Results from different clients look the same, whether you're requesting a call from an iOS app, a web browser, or a command line script. There are four components of a uniform interface:

• identification of resources - The request must include a resource identifier.
• manipulation of resources through representations - The response must include enough information so the client can modify the resource.
• self-descriptive messages - Each request must contain all the information the server needs to perform the request, and each response must contain all the information the client needs to understand the response. No information must be assumed on either the client or the server's end.
• hypermedia as the engine of application state - This means that in a response, the server can tell the client about ways to change the state of the application, typically via including links to perform these actions.

Client-server separation

This is one of the fundamental principles of the RESTful API. The client and the server each act separately. The client sends out the requests, and the server sits and waits for the requests to come in, then sends a response only when the client sends a request. Either the client or the server can be replaced at any time without affecting the other.

Stateless

Session state is stored on the client. This means that the server makes no assumptions about whether the user made a similar API request in the past, or what resources the user has requested before. Each request is independent.

Cacheable

The data within a response must be labeled as cacheable or non-cacheable. If a response is labeled as cacheable, it typically contains a version number and an expiration date. If the response is cacheable, then a client cache may reuse that data for future use (after checking that the cached data is still current). This ensures that clients do not request exactly the same data over and over.

Layered system

There may be servers in between the client making the request and the server sending the response. Some layers in this interface may include servers for security, speed, or caching, to name a few. However, these layers do not interfere with the information being sent between the client and the server.

Code-on-demand

This constraint is optional. An API can still be considered RESTful without this sixth constraint. The code-on-demand constrant ensures that the client can request code from the server, which the server will then return. The client can execute this code. [Does Revel's API do this?]