from unrest to rest
TRANSCRIPT
3
This presentation is not just inspired, but rather ripped off from Martin Fowler’s article. Please read it.
Why bother creating this?Its easier to discuss things to a team of young engineers with a visual stuff in the background rather than a document
As Martin suggests in the original article, this is for conceptual understanding; not a technical elaboration. For such a treatment, refer to RedHat’s https://restful-api-design.readthedocs.org/en/latest/ .
REFERENCES
Book a 1x1 meeting with your co-worker
Service Definition
Allows users to book an 1x1 appointment with their co-workers
4
Appointment Service – unREST
7
POST http://<server>/appointmentService
<openSlotRequest date = "2010-01-04" worker = "mjones"/>
<openSlotList>
<slot start = "1400" end = "1450">
<worker id = "mjones"/>
</slot>
<slot start = "1600" end = "1650">
<worker id = "mjones"/>
</slot>
</openSlotList>
POST http://<server>/appointmentService
<appointment>
<slot worker = "mjones" start = "1400" end = "1450"/>
<requestor id = "jsmith"/>
</appointment>
<appointmentRequestFailure>
<slot worker = "mjones" start = "1400" end = "1450"/>
<requestor id = "jsmith"/>
<reason>Slot not available</reason>
</appointmentRequestFailure>
OR
<appointmentRequest>
<slot worker = "mjones" start = "1400" end = "1450"/>
<requestor id = "jsmith"/>
</appointmentRequest>
HTTP/1.1 200 OK
Appointment Service – unREST
8
POST http://<server>/appointmentService
<openSlotRequest date = "2010-01-04" worker = "mjones"/>
<openSlotList>
<slot start = "1400" end = "1450">
<worker id = "mjones"/>
</slot>
<slot start = "1600" end = "1650">
<worker id = "mjones"/>
</slot>
</openSlotList>
POST http://<server>/appointmentService
<appointmentRequest>
<slot worker = "mjones" start = "1400" end = "1450"/>
<requestor id = "jsmith"/>
</appointmentRequest>
HTTP/1.1 200 OK
<appointment>
<slot worker = "mjones" start = "1400" end = "1450"/>
<requestor id = "jsmith"/>
</appointment>
<appointmentRequestFailure>
<slot worker = "mjones" start = "1400" end = "1450"/>
<requestor id = "jsmith"/>
<reason>Slot not available</reason>
</appointmentRequestFailure>
OR
Appointment Service – unREST
9
POST http://<server>/appointmentService
<openSlotRequest date = "2010-01-04" worker = "mjones"/>
<openSlotList>
<slot start = "1400" end = "1450">
<worker id = "mjones"/>
</slot>
<slot start = "1600" end = "1650">
<worker id = "mjones"/>
</slot>
</openSlotList>
POST http://<server>/appointmentService
<appointmentRequest>
<slot worker = "mjones" start = "1400" end = "1450"/>
<requestor id = "jsmith"/>
</appointmentRequest>
HTTP/1.1 200 OK
<appointment>
<slot worker = "mjones" start = "1400" end = "1450"/>
<requestor id = "jsmith"/>
</appointment>
<appointmentRequestFailure>
<slot worker = "mjones" start = "1400" end = "1450"/>
<requestor id = "jsmith"/>
<reason>Slot not available</reason>
</appointmentRequestFailure>
OR
You need to know these
methods and the order in
which they should be called
etc. – how?
Why OK for both success
and failure?
You now want provide a service to
add accessories, say projector, for
your meeting. How would you do it?
Appointment Service – REST 1/3
12
POST http://<server>/workers/mjones
<openSlotRequest date = "2010-01-04"/>
<openSlotList>
<slot id = "1234" worker = "mjones" start = "1400" end = "1450"/>
<slot id = "5678" worker = "mjones" start = "1600" end = "1650"/>
</openSlotList>
POST http://<server>/slots/1234
<appointment>
<slot id = “1234" worker = "mjones" start = "1400" end = "1450"/>
<requestor id = "jsmith"/>
</appointment>
<appointmentRequest>
<requestor id = "jsmith"/>
</appointmentRequest>
HTTP/1.1 200 OK
Appointment Service – REST 1/3
13
POST http://<server>/workers/mjones
<openSlotRequest date = "2010-01-04"/>
<openSlotList>
<slot id = "1234" worker = "mjones" start = "1400" end = "1450"/>
<slot id = "5678" worker = "mjones" start = "1600" end = "1650"/>
</openSlotList>
POST http://<server>/slots/1234
<appointment>
<slot id = “1234" worker = "mjones" start = "1400" end = "1450"/>
<requestor id = "jsmith"/>
</appointment>
<appointmentRequest>
<requestor id = "jsmith"/>
</appointmentRequest>
HTTP/1.1 200 OK
URL endpoints are simply
resources themselves
Appointment Service – REST 2/3
16
GET http://<server>//workers/mjones/slots?date=20100104&status=open
<openSlotList>
<slot id = "1234" worker = "mjones" start = "1400" end = "1450"/>
<slot id = "5678" worker = "mjones" start = "1600" end = "1650"/>
</openSlotList>
POST http://<server>/slots/1234
<appointment>
<slot id = “1234" worker = "mjones" start = "1400" end = "1450"/>
<requestor id = "jsmith"/>
</appointment>
<appointmentRequest>
<requestor id = "jsmith"/>
</appointmentRequest>
HTTP/1.1 201 Created
<appointmentRequestFailure>
<slot worker = "mjones" start = "1400" end = "1450"/>
<requestor id = "jsmith"/>
<reason>Slot not available</reason>
</appointmentRequestFailure>
ORHTTP/1.1 409 Conflict
Appointment Service – REST 2/3
17
GET http://<server>//workers/mjones/slots?date=20100104&status=open
<openSlotList>
<slot id = "1234" worker = "mjones" start = "1400" end = "1450"/>
<slot id = "5678" worker = "mjones" start = "1600" end = "1650"/>
</openSlotList>
POST http://<server>/slots/1234
<appointment>
<slot id = “1234" worker = "mjones" start = "1400" end = "1450"/>
<requestor id = "jsmith"/>
</appointment>
<appointmentRequest>
<requestor id = "jsmith"/>
</appointmentRequest>
HTTP/1.1 201 Created
<appointmentRequestFailure>
<slot worker = "mjones" start = "1400" end = "1450"/>
<requestor id = "jsmith"/>
<reason>Slot not available</reason>
</appointmentRequestFailure>
ORHTTP/1.1 409 Conflict
Use the right HTTP
verbs
Rely on HTTP error
codes
HTTP caching is enabled –
router, load-balancer etc. will also
cache our application traffic
Appointment Service – REST 3/3
20
GET http://<server>//workers/mjones/slots?date=20100104&status=open
<openSlotList>
<slot id = "1234" worker = "mjones" start = "1400" end = "1450">
<link rel = "/linkrels/slot/book"
uri = "/slots/1234"/>
</slot>
<slot id = "5678" worker = "mjones" start = "1600" end = "1650">
<link rel = "/linkrels/slot/book"
uri = "/slots/5678"/>
</slot>
</openSlotList>POST http://<server>/slots/1234
<appointment>
<slot id = “1234" worker = "mjones" start = "1400" end = "1450"/>
<requestor id = "jsmith"/>
<link rel = "/linkrels/appointment/cancel"
uri = "/slots/1234/appointment"/>
<link rel = "/linkrels/appointment/addAccessory"
uri = "/slots/1234/appointment/accessories"/>
<link rel = "self"
uri = "/slots/1234/appointment"/>
<link rel = "/linkrels/appointment/changeTime"
uri = "/workers/mjones/slots?date=20100104@status=open"/>
<link rel = "/linkrels/help"
uri = "/help/appointment"/>
</appointment>
<appointmentRequest>
<requestor id = "jsmith"/>
</appointmentRequest>
HTTP/1.1 201 Created
Location: Location: http://royalhope.nhs.uk/slots/1234/appointment
<appointment>
<slot id = "1234" worker = "mjones" start = "1400" end = "1450"/>
<requestor id = "jsmith"/>
<link rel = "/linkrels/appointment/cancel"
uri = "/slots/1234/appointment"/>
<link rel = "/linkrels/appointment/addAccessory"
uri = "/slots/1234/appointment/tests"/>
<link rel = "self"
uri = "/slots/1234/appointment"/>
<link rel = "/linkrels/appointment/changeTime"
uri = "/workers/mjones/slots?date=20100104@status=open"/>
<link rel = "/linkrels/help"
uri = "/help/appointment"/>
</appointment>
Appointment Service – REST 3/3
21
GET http://<server>//workers/mjones/slots?date=20100104&status=open
<openSlotList>
<slot id = "1234" worker = "mjones" start = "1400" end = "1450">
<link rel = "/linkrels/slot/book"
uri = "/slots/1234"/>
</slot>
<slot id = "5678" worker = "mjones" start = "1600" end = "1650">
<link rel = "/linkrels/slot/book"
uri = "/slots/5678"/>
</slot>
</openSlotList>POST http://<server>/slots/1234
<appointmentRequest>
<requestor id = "jsmith"/>
</appointmentRequest>
HTTP/1.1 201 Created
Location: Location: http://royalhope.nhs.uk/slots/1234/appointment
Server communicates the URI for
various services offered on this
resource. Clients simply lookup (say,
‘book’) and use the URI
Adding an accessory to an existing
meeting slot, is as simple as adding
link and URI for it.
23
REST 1/3 tackles the question of handling complexity by using divide and conquer, breaking a large service endpoint down into multiple resources.
REST 2/3 introduces a standard set of verbs so that we handle similar situations in the same way, removing unnecessary variation.
REST 3/3 introduces discoverability, providing a way of making a protocol more self-documenting.
In Martin Fowler’s words