12. REST API Design

Hypertext Transfer Protocol (HTTP)

- A communications protocol - Allows retrieving inter-linked text documents (hypertext)

HTTP Verbs

- HEAD - GET - POST - PUT - DELETE - TRACE - OPTIONS - CONNECT

Actions to be performed on resources

- HTTP GET - HTTP POST - HTTP PUT - HTTP DELETE

RESTful architecture is associated with

- Well-defined URIs that "represent" resource such as "/posts" on a blog representing posts on the blog - HTTP methods being used as verbs to perform actions on that resource (i.e., GET for reading posts, POST for writing posts) - The ability to access multiple format representations of the data (i.e., JSON and XML representations of a blog post) - Sending HTTP status codes for a more detailed response

REST consists of constraints

1. Client - Server 2. Stateless 3. Cache 4. Uniform Interface 5. Layered System

Constrained/Unconstrained Concepts in REST

1. Nouns (Resources) - unconstrained 2. Verbs - constrained 3. Representations - constrained

Different Types of Web APIs

1. Remote Procedure Call, RPC. - Clients can call functions on the server. 2. Remote Method Invocation, RMI. - Clients can call methods on objects on the server. 3. Representational State Transfer, REST. - Clients can apply CRUD (Create, Read, Update and Delete) operations on resources on the server.

Resource

A conceptual mapping to a set of entities. Any information that can be named can be a resource. It is represented with a global identifier (URI in HTTP)

Client - Server

A pull based interaction cycle (Client requests data from servers as and when needed).

Uniform interface

All resources are accessed with a generic interface (e.g., HTTP GET, POST, PUT, DELETE).

Representational State Transfer

Defines certain rules the API will follow

Query string: additional info about resource

Describe what you're looking for. Key/value pairs, separated by &. Keys and values are URI encoded. $.g., ?

Resources

Each "thing" we want to send/receive is a "resource" identified by a URI (path).

Stateless

Each request from client to server must contain all the information necessary to understand the request, and cannot take advantage of any stored context on the server.

To specify the data format for the resources, use ...

HTTP headers Content-Type and Accept.

To specify operations, use ...

HTTP methods: 1. Create - POST (or PUT) 2. Retrieve - GET 3. Update - PUT (or PATCH) 4. Delete - DELETE

To indicate success/failure, use ...

HTTP status code.

API

It can be defined as a set of functions and procedures allowing the creation of applications that access the features or data of an operating system, application, or other service.

The method to update parts of a resource

PATCH. PATH method is only a proposed standard.

HTTP requests

Query string, headers (info about request), Body: data sent to server

REST

REST is an architechtural style for providing standards between computer systems on the web, making it easier for systems to communicate with each other.

Statelessness

Server doesn't "remember" clients. In other words, each request includes URI, other info. The server does not store any session information between requests, which can simplify server design and improve scalability.

HTTP responses

Status code: result of request, headers - info about the response (the type of server, the type of response data), body (the resource, error message, etc.).

From Roy's Dissertation the Meaning of REST

The name "Representational State Transfer" is intended to evoke an image of how a well-designed Web application behaves: a network of web pages (a virtual state-machine), where the user progresses through the application by selecting links (state transitions), resulting in the next page (representing the next state of application) being transferred to the user and rendered for their use.

Interconnected resource representations

The representations of the resources are interconnected using URLs, thereby enabling a client to progress from one state to another.

Named resources

The system is comprised of resources which are named using a URL.

Cache

To improve network efficiency, responses must be capable of being labeled as cacheable or non-cacheable.

PUT can also be used to create a resource if you know which URI it should have in advance.

True

REST is an architectural style, not a specification.

True

REST is not a standard, but it uses several standards.

True

REST is the underlying architectural model of the World Wide Web and the guiding framework for Web protocol standards.

True

The Web is an example of a REST system.

True

To identify resources, use ...

URIs

The key abstraction of information in REST

a resource

As you traverse the path from more ... to more ..., you are navigating the data.

generic, specific

Servers return "..." of the resource.

representation such as xml, json, etc. Clients send (possibly partial) representations to update resources.

Principles of REST Web Service Design

◼ 1.Identify all the conceptual entities that we wish to expose as services. (Examples we saw include resources such as : parts list, detailed part data, purchase order) ◼ 2. Create a URL to each resource. ◼ 3. Categorize our resources according to whether clients can just receive a representation of the resource (using an HTTP GET), or whether clients can modify (add to) the resource using HTTP POST, PUT, and/or DELETE). ◼ 4. All resources accessible via HTTP GET should be side-effect free. That is, the resource should just return a representation of the resource. Invoking the resource should not result in modifying the resource. ◼ 5.Put hyperlinks within resource representations to enable clients to drill down for more information, and/or to obtain related information. ◼ 6. Design to reveal data gradually. Don't reveal everything in a single response document. Provide hyperlinks to obtain more details. ◼ 7. Specify the format of response data using a schema (DTD, W3C Schema, RelaxNG, or Schematron). For those services that require a POST or PUT to it, also provide a schema to specify the format of the response. ◼ 8. Describe how our services are to be invoked using either a WSDL document, or simply an HTML document.