@nabeelxy

5/9/2016

Customers are requesting for a REST API to talk to our popular Menu App.

What exactly is REST? How is it working? Where do we start? How

much work does it involve?

Tom, Menu App Manager Jim, Backend Dev

REST is nothing new actually. We have been using REST every day. Let me explain.

REST HTTP

(Architectural Pattern) (One Realization of this pattern)

Jim, Backend Dev

A REST API works pretty much the same way a web

request works.

(1) HTTP Request

(2) HTTP Response

HTTP GET Request (Web Request)

HTTP Response as an HTML

HTTP GET Request (HTTP REST API Request)

HTTP Response in JSON format

(Resource-oriented programming)

Fundamental building blocks of Web based systems

URI (Uniform Resource Identifier) uniquely identifies a resource

Uniform interface to manipulate a resource (CRUD)

The same resource can be represented in multiple formats

Collection resources E.g. customers

REST: /customers

Instance resources E.g. a specific customer

REST: /customers/customer1

How can we perform operations on the resources identified by URIs?

Tom, Menu App Manager

HTTP CRUD Description

GET Retrieve Safe, Idempotent, Cacheable

POST Create -

PUT Update Idempotent

DELETE Delete Idempotent

Client-Server

Stateless Session state on the client

Cacheable A response can be cacheable

Layered system

Code on demand (optional) Extension after deployment

Uniform interface

Let’s build a simple REST Book application to put things together.

Jim, Backend Dev

Assume that we have a class called Book and we want to expose its

functionality via a REST API.

To make our REST application simple, let’s say we are exposing one single

book and we just want to get information about the book in

different formats (plaintext, JSON).

Jim, Backend Dev

Base URL: http://nabeel.com/MyRest/api/

Resource formats (two formats) application/json text/plain

Behavior GET (get information about the book)

Development Language: Java

JAX-RS (Java API for RESTful Web Services) Standard annotation-driven API

JAX-RS 2.x is the latest version

We use the Jersey implementation of this standard

Deploy in Tomcat (web.xml should be updated accordingly)

Tomcat

book.war

JAX-RS resource (book)

GET /book HTTP/1.1

Accept: application/json

HTTP/1.1 200 OK

Content-type: application/json

{

“title”: “The Future of the Mind”,

“author”: “Michio Kaku”

}

<?xml version="1.0" encoding="UTF-8"?>

<web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://xmlns.jcp.org/xml/ns/javaee" xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee http://xmlns.jcp.org/xml/ns/javaee/web-app_3_1.xsd" id="WebApp_ID" version="3.1">

<display-name>MyRest</display-name>

<servlet>

<display-name>Rest Servlet</display-name>

<servlet-name>RestServlet</servlet-name>

<servlet-class> org.glassfish.jersey.servlet.ServletContainer </servlet-class>

<init-param>

<param-name>com.sun.jersey.config.property.packages</param-name>

<param-value>com.nabeel.resources</param-value>

</init-param>

</servlet>

<servlet-mapping>

<servlet-name>RestServlet</servlet-name>

<url-pattern>/api/*</url-pattern>

</servlet-mapping>

</web-app>

You need to define your RESTful classes under this

package.

JAX-RS 2.x

package com.nabeel.resources;

import javax.ws.rs.GET;

import javax.ws.rs.Path;

import javax.ws.rs.Produces;

import javax.ws.rs.core.MediaType;

@Path("/book")

public class Book {

@GET

@Produces(MediaType.TEXT_PLAIN)

public String getBookPlain() {

return "<book description in plaintext>";

}

@GET

@Produces(MediaType.APPLICATION_JSON)

public String getBookJson() {

return "<book description in json>";

}

}

GET /book HTTP/1.1 Accept: application/json

Invoke Book.getBookJson

HTTP/1.1 200 OK Content-type: application/json { “title”: “The Future of the Mind”, “author”: “Michio Kaku” }

REST request: http://nabeel.com/MyRest/api/book

Tomcat application container processing the request and producing the result

REST response in JSON format

This is only the tip of the iceberg

Designing RESTful APIs Richardson Maturity Model

HATEOAS principles

Versioning

Error handling

Security

Scaling (Caching)

Jim Webber, Savas Parastatidis, Ian Robinson, REST in Practice, 2010