REST API Design

Application API API = Application Programming Interface APIs expose functionality of an application or service that exists independently of the API. Examples: Facebook Twitter Google

REST REST stands for Representational State Transfer REST is an architectural style for networked hypermedia applications REST is used to build Web services that are lightweight, maintainable, and scalable. REST is not dependent on any protocol, but almost every RESTful service uses HTTP as its underlying protocol.

RESTful Design Components There are three distinct components involved in RESTful API design: 1.the application 2.the API code 3.the client.

Resources The fundamental concept in any RESTful API is the resource. Resources model objects from the application data model. These resources can be pictures, video files, Web pages, business information, etc. A resource is an object with a type, associated data, relationships to other resources, and a set of methods that operate on it. Each resource has a unique URL

Addressing Resources A RESTful service uses a directory hierarchy like human readable URIs to address its resources. The job of a URI is to identify a resource or a collection of resources. The actual operation is determined by an HTTP verb. The URI should not say anything about the operation or action. This enables us to call the same URI with different HTTP verbs to perform different operations. Bad: Example resource:

Collections Resources can be grouped into collections. Each collection is homogeneous so that it contains only one type of resource. Collections are unordered. Collections are themselves resources as well. Example collection:

Resource Model of an API The resource model of an API consists: 1.Available resources types 2.Their behavior 3.Their relationships The resource model can be viewed as the RESTful mapping of the application data model.

Resource Data Resources have data associated with them. In JSON, just three types of data exist: scalar (number, string, boolean, null). array object Data associated with a resource is modeled as key:value pairs on the JSON object.

JSON Object Example

REST Metadata In addition to exposing application data, resources also include other information that is specific to the RESTful API. Such information includes URLs and relationships. Example: { "href" : " "username" : "jlpicard", " " : "directory" : { "href" : " }, … }

Entry Point A RESTful API needs to have one and exactly one entry point. The URL of the entry point needs to be communicated to API clients so that they can find the API. It is common for the entry point to contain some or all of the following information: Information on API version, supported features, etc. A list of top-level collections. A list of singleton resources Each collection and resource in the API has its own URL. URLs should never be constructed by an API client. Instead, the client should only follow links that are generated by the API itself.

Messages The client and service talk to each other via messages. Clients send a request to the server, and the server replies with a response. Apart from the actual data, these messages also contain some metadata about the message. HTTP Request:

Request Message Example POST Host: MyService.com Content-Type: text/xml; charset=utf-8 Content-Length: 123 Larry US

Response Message Example HTTP/ OK Date: Sat, 23 Aug :31:04 GMT Server: Apache/2 Last-Modified: Wed, 01 Sep :24:52 GMT Accept-Ranges: bytes Content-Length: Cache-Control: max-age=21600, must-revalidate Expires: Sun, 24 Aug :31:04 GMT Content-Type: text/html; charset=iso CS449 Calendar...

Methods Methods are verbs or actions that can be performed on resources Methods can be executed on resources via their URL. Standard methods that have a well-defined meaning for all resources and collections: MethodScopeSemanticsQuality GETCollectionRetrieve all resources in a collectionSafe GETResourceRetrieve a single resourceSafe POSTCollectionCreate a new resource in a collectionN/A PUTResourceUpdate a resourceIdempotent DELETEResourceDelete a resourceIdempotent HEADResourceRetrieve only the response headersSafe OPTIONSResourceList the allowed operations on a resource.Safe

Methods [cont.] GET is Safe. A Safe operation is an operation that does not have any effect on the original value of the resource. PUT and DELETE are Idempotent. An Idempotent operation is an operation that gives the same result no matter how many times you perform it. Note, if you are adding a resource with PUT you have to specify the unique ID of the resource.

Difference between PUT and POST PUT is idempotent while POST is not. No matter how many times you send a PUT request, the results will be same. POST is not an idempotent method. Making a POST multiple times may result in multiple resources getting created on the server. With PUT, it is the client's job to choose a unique name or ID for the resource. With POST, the server decides. This is why POST is not idempotent. There is no difference between PUT and POST if the resource already exists

Options The method OPTIONS is used to get a list of allowed operations on the resource. For example Request: OPTIONS HTTP/1.1 HOST: api.business.com Response: 200 OK Allow: HEAD, GET, PUT

Relationships Resources do not exist in isolation, but have relationships to other resources. A resource representation can contain links to other resources. The representations returned by the service should drive the process flow as in case of a website. When you visit any website, you are presented with an index page. You click one of the links and move to another page and so on. Relationships are defined via link object or href attribute.

Stateless A RESTful service is stateless and does not maintain the application state for any client. A request cannot be dependent on a past request and a service treats each request independently. HTTP is a stateless protocol by design and you need to do something extra to implement a stateful service using HTTP. Example stateful design (not RESTful): Request1: GET HTTP/1.1 Request2: GET HTTP/1.1

HATEOAS HATEOAS = Hypermedia as the Engine of Application State HATEOAS is a constraint of the REST application architecture that distinguishes it from most other network application architectures. HATEOAS is how the web works. Ever notice how the websites amazon.com, google.com, twitter.com etc. don’t come with an instruction manual for using them? You don’t need one. You simply discover the features of a website by following hyperlinks. Nice feature of the web because otherwise every time there was a change to the structure of a website the website user guide would have to be updated, redistributed and reread. Websites are freer to evolve because they are built on the concept of HATEOAS.

HATEOAS API A REST client enters a REST application through a simple fixed URL. All future actions the client may take are discovered within resource representations returned from the server. The client transitions through application states by selecting from the links within a representation or by manipulating the representation in other ways afforded by its media type. In this way, RESTful interaction is driven by hypermedia, rather than out-of-band information (written documentation)

Example Non-HATEOAS Response: { "name": "Alice", } HATEOAS Response: { "name": "Alice", "links": [ { "rel": "self", "href": " } ] }