What is it ?

REpresentational State Transfer

• Architectural style for distributed Hypermedia systems
• Invented by Roy Fielding

  

  • in 2000
  • in chapter 5 of his doctoral dissertation

Technical Generalities

• Client / Server
• Over HTTP
  • Cache
  • Verbs
  • Status codes
• Stateless

Conceptual Generalities

• Collections
• Identified resources
• For machines and humans

REST vs SOAP

Richardson's Maturity Model

• The level of REST implementation reflects the maturity of :
  • Teams
  • Products

REST level 0

Just a tunnel for remote invocation mechanism

POST /appointmentService HTTP/1.1

{ date: "2010-01-24", doctor: "martin" }

HTTP/1.1 200 OK

{ openSlotList: [
  { start: 1400, end: 1450, doctor: "martin" },
  { start: 1600, end: 1650, doctor: "martin" }
]}

POST /appointmentService HTTP/1.1

{ 
    slot: { start: 1400, end: 1450, doctor: "martin" },
    patient: { id: "brown" }
}

HTTP/1.1 200 OK

{ 
    slot: { start: 1400, end: 1450, doctor: "martin" },
    patient: { id: "brown" }
}

HTTP/1.1 200 OK

{ 
    error: "Booking failure"
}

REST level 1

Start to talk to identifed resources

POST /doctors/martin HTTP/1.1

{ date: "2010-01-24" }

HTTP/1.1 200 OK

{ openSlotList: [
    { id: 1234, start: 1400, end: 1450, doctor: "martin" },
    { id: 5678 start: 1600, end: 1650, doctor: "martin" }
]}

POST /slots/1234 HTTP/1.1

{ 
    patient: { id: "brown" }
}

HTTP/1.1 200 OK

{ 
    slot: { start: 1400, end: 1450, doctor: "martin" },
    patient: { id: "brown" }
}

REST level 2

Start to use HTTP verbs and status codes

GET /doctors/martin/slots?date=20100104&status=open HTTP/1.1

HTTP/1.1 200 OK

{ openSlotList: [
    { id: 1234, start: 1400, end: 1450, doctor: "martin" },
    { id: 5678 start: 1600, end: 1650, doctor: "martin" }
]}

POST /slots/1234 HTTP/1.1

{ 
    patient: { id: "brown" }
}

HTTP/1.1 201 Created
Location: slots/1234/appointment

{ 
    slot: { start: 1400, end: 1450, doctor: "martin" },
    patient: { id: "brown" }
}

REST level 3

Hypermedia As The Engine Of Application State

GET /doctors/martin/slots?date=20100104&status=open HTTP/1.1

HTTP/1.1 200 OK

{ openSlotList: [
    { id: 1234, start: 1400, end: 1450, doctor: "martin", 
      links: [ {rel: "book", uri: "/slots/1234 } ] },
    { id: 5678 start: 1600, end: 1650, doctor: "martin" , 
      links: [ {rel: "book", uri: "/slots/5678 } ] } ]}

POST /slots/1234 HTTP/1.1

{ 
    patient: { id: "brown" }
}

HTTP/1.1 201 Created
Location: slots/1234/appointment

{ slot: { start: 1400, end: 1450, doctor: "martin" },
  patient: { id: "brown" }, links: [ 
    { rel: "self", uri: "/slots/1234/appointment" } ] },
    { rel: "cancel", uri: "/slots/1234/appointment" } ] } }

Operations & HTTP verbs

Querystrings

https://api.book-a-doctor.com/doctors/martin/slots?filter=date+eq+20100104+and+status+eq+open&limit=25

• filter : filter to apply to elements to return

• offset : index of first element to return

• limit : maximal number of elements to return

• sort : sorting of elements to return

This is just an example of a possible implementation. This is not standard.

Content negociation

• Client's preferences are indicated in Accept header (format, language, encoding, etc ...)

• Server answers as best as it can to client's expectations

Status codes

Usefull links

• Nobody understands REST : http://williamdurand.fr/2015/06/02/video-nobody-understands-rest

• Webservices with Spring : http://spring.io/guides/tutorials/bookmarks/

• HATEOS : https://en.wikipedia.org/wiki/HATEOAS

It's your turn

Let's expose APIs !