Be 

RESTful !

by @xavierhanin


http://slid.es/xavierhanin/be-restful




/me

Xavier Hanin




Lead Architect / Developer
Bordeaux Agency Manager
@ 4SH

Community

Creator of BordeauxJUG (2008)

Frequent speaker (Devoxx BE, Devoxx FR, ApacheCon, JavaZone, BordeauxJUG, ...)

Teacher @ Institut Polytechnique de Bordeaux (2004->2016)

Winner of CodeStory S02


Open Source

Creator of Apache Ivy (2004)
Creator of Voxxr.in (2012)

Many side projects / contributions
wicket-contrib-push, xooki, xooctory, twitter4j, ...

Creator of RESTX (2013)

Web Development


Servlet, JSP, Velocity, Freemarker, JSTL, JSF, RichFaces, ADF Faces, Wicket, GWT, Struts, Spring MVC, Restlet, Play! Framework, SimpleFramework, PHP, HTML5, CSS3, JS, NodeJS, Dojo, ExtJS, jQuery, AngularJS

REST


Representational State Transfer


Architecture Style


Web


Roy Fielding Thesis (2000)

Elements



Resources

Resources Identifiers

Representations

Constraints


Client Server
Stateless
Cacheable
Uniform Interface
Layered System
Code On Demand (optional)

RESTful Web Services

Resource


Any information that can be named can be a resource - Roy Fielding

A person
The list of persons living in Bordeaux
Today's weather in La Rochelle

Resource Identifier

URI = Uniform Resource Identifier
^
|
URL = Uniform Resource Locator

eg
http://restx.io/modules
http://en.wikipedia.org/wiki/Main_Page

Representation


REST components perform actions on a resource by using a representation to capture the current or intended state of that resource and transferring that representation between components - Roy Fielding

Representation

JSON 
{
    "name":"Acme Inc",
    "address": {
        "body":"111, av du truc",
        "zipCode":"33700",
        "city":"Merignac"
    },
    "_id":"51eba5766bc8e48ffeaacc89"
}
XML 
<company name="Acme Inc" _id="51eba5766bc8e48ffeaacc89">
        <address>
            <body>111, av du truc</body>
            <zipcode>33700</zipcode>
            <city>Merignac</city>
        </address>
    </company>

Uniform interface

HTTP Methods

GET
HEAD
OPTIONS
PUT
POST
DELETE
TRACE
CONNECT

GET

get a resource state representation
nullipotent 

GET /companies/51ebab006bc8e48ffeaacc93
HTTP/1.1 200 OK
Date: Mon, 01 Dec 2008 01:15:39 GMT
Content-Type:application/json; charset=UTF-8

{    "name":"ACME Inc",
    "address":{
        "body":"1122, pooder st",        "zipCode":"12345 CA",        "city":"Palo Alto"},
    "_id":"51ebab006bc8e48ffeaacc93"
}

HEAD

get a resource metadata
nullipotent

eg 
HEAD /companies/51ebab006bc8e48ffeaacc93
HTTP/1.1 200 OK
Date: Mon, 01 Dec 2008 01:15:39 GMT
Content-Type:application/json; charset=UTF-8

OPTIONS

request for information about the communication options available
nullipotent

eg
Used for CORS (Cross Origin Resource Sharing)
OPTIONS /companies/51ebab006bc8e48ffeaacc93
Origin: http://foo.example
Access-Control-Request-Method: PUT

HTTP/1.1 200 OK
Date: Mon, 01 Dec 2008 01:15:39 GMT
Access-Control-Allow-Origin: http://foo.example
Access-Control-Allow-Methods: PUT, POST, GET, OPTIONS

PUT

put a resource state representation
idempotent 
PUT /companies/51ebab006bc8e48ffeaacc93
        
{   "name":"ACME Inc",
    "address":{
        "body":"1122, pooder st",
        "zipCode":"12345 CA",
        "city":"Palo Alto"},
    "_id":"51ebab006bc8e48ffeaacc93"}        
    
HTTP/1.1 200 OK

{   "name":"ACME Inc",
    "address":{
        "body":"1122, pooder st",
        "zipCode":"12345 CA",
        "city":"Palo Alto"},
    "_id":"51ebab006bc8e48ffeaacc93"}

DELETE

deletes a resource
idempotent

eg
DELETE /companies/51ebab006bc8e48ffeaacc93
HTTP/1.1 204 No Content

POST

posts a new resource state representation
"request that the origin server accept the entity enclosed in the request as a new subordinate of the resource"
POST /companies
        
{   "name":"ACME Inc",
    "address":{
        "body":"1122, pooder st",
        "zipCode":"12345 CA",
        "city":"Palo Alto"} }        
    
HTTP/1.1 201 Created

{   "name":"ACME Inc",
    "address":{
        "body":"1122, pooder st",
        "zipCode":"12345 CA",
        "city":"Palo Alto"},
    "_id":"51ebab006bc8e48ffeaacc93"}

Uniform Interface

HTTP status codes
200 OK 
201 Created 
202 Accepted 
204 No Content 
301 Moved Permanently 
303 See Other 
304 Not Modified
...
400 Bad Request 
401 Unauthorized 
403 Forbidden 
404 Not Found
500 Internal Server Error
...


Stateless


such that each request from client to server must contain all of the information necessary to understand the request, and cannot take advantage of any stored context on the server. Session state is therefore kept entirely on the client. - Roy Fielding

Resource Design




Extremely "Object" oriented
Forget about actions
Everything is an object

Resource Design


Example : a content publishing workflow

A writer writes some content, then submits his draft for approval.
A publisher approves the draft, which is then published

Procedure


  1. Figure out the data set

  2. Split the data set into resources

    For each kind of resource:

  3. Name the resources with URIs

  4. Expose a subset of the uniform interface 

5. Design the representation(s) accepted from the client
6. Design the representation(s) served to the client
7. Integrate this resource into existing resources, using hypermedia links and forms 

8. Consider the typical course of events: what’s supposed to happen?
9. Consider error conditions: what might go wrong? 

Figure out the dataset


Which data for your application?

Split into resources


Predefined one-off resources for especially important aspects of the application.

A resource for every object exposed through the service.

Resources representing the results of algorithms applied to the data set. 

Name the resources


  1. Use path variables to encode hierarchy: /parent/child

  2. Put punctuation characters in path variables to avoid implying hierarchy where

    none exists: /parent/child1;child2

  3. Use query variables to imply inputs into an algorithm, for exam- ple: /search?q=jellyfish&start=20 

Going further


RESTX





Thank you !


Questions?

Links

http://www.ietf.org/rfc/rfc2616.txt
https://github.com/andreineculau/know-your-http-well
http://kellabyte.com/2011/09/04/clarifying-rest/
http://www.restapitutorial.com/
http://amzn.to/3V0qPn

http://restx.io/
Made with Slides.com