From unREST to REST

Concept clarity series

Anand, 19-Feb-2015

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

http://martinfowler.com/articles/richardsonMaturityModel.html

https://restful-api-design.readthedocs.org/en/latest/

Book a 1x1 meeting with your co-worker

Service Definition

Allows users to book an 1x1 appointment with their co-workers

4

Implement a method (remote method, XML-RPC, SOAP etc.)

Appointment Service – unREST

6


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">


</slot>

</openSlotList>


<appointment>

<slot worker = "mjones" start = "1400" end = "1450"/>

<requestor id = "jsmith"/>

</appointment>

<appointmentRequestFailure>



<reason>Slot not available</reason>

</appointmentRequestFailure>

OR

<appointmentRequest>



</appointmentRequest>

HTTP/1.1 200 OK


8



<openSlotList>

<slot start = "1400" end = "1450">


</slot>

<slot start = "1600" end = "1650">


</slot>

</openSlotList>






HTTP/1.1 200 OK

<appointment>



</appointment>






OR


9



<openSlotList>

<slot start = "1400" end = "1450">


</slot>

<slot start = "1600" end = "1650">


</slot>

</openSlotList>






HTTP/1.1 200 OK

<appointment>



</appointment>






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?

Offer your resources instead of services

Appointment Service – REST 1/3

11

workers/mjones


12

POST http://<server>/workers/mjones

<openSlotRequest date = "2010-01-04"/>

<openSlotList>

<slot id = "1234" worker = "mjones" start = "1400" end = "1450"/>


</openSlotList>

POST http://<server>/slots/1234

<appointment>

<slot id = “1234" worker = "mjones" start = "1400" end = "1450"/>


</appointment>




HTTP/1.1 200 OK


13

POST http://<server>/workers/mjones

<openSlotRequest date = "2010-01-04"/>

<openSlotList>



</openSlotList>


<appointment>



</appointment>




HTTP/1.1 200 OK

URL endpoints are simply

resources themselves

GET, PUT/POST


15

workers/mjones/slots


16

GET http://<server>//workers/mjones/slots?date=20100104&status=open

<openSlotList>



</openSlotList>


<appointment>



</appointment>




HTTP/1.1 201 Created






ORHTTP/1.1 409 Conflict


17


<openSlotList>



</openSlotList>


<appointment>



</appointment>










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

http://www.w3.org/Protocols/rfc2616/rfc2616-sec13.html

HATEOAS (Hypertext As The Engine Of Application State) , Descriptive XML/JSON


19

workers/mjones/slots


20


<openSlotList>

<slot id = "1234" worker = "mjones" start = "1400" end = "1450">

<link rel = "/linkrels/slot/book"

uri = "/slots/1234"/>

</slot>



uri = "/slots/5678"/>

</slot>

</openSlotList>POST http://<server>/slots/1234

<appointment>



<link rel = "/linkrels/appointment/cancel"

uri = "/slots/1234/appointment"/>

<link rel = "/linkrels/appointment/addAccessory"

uri = "/slots/1234/appointment/accessories"/>

<link rel = "self"


<link rel = "/linkrels/appointment/changeTime"

uri = "/workers/mjones/slots?date=20100104@status=open"/>

<link rel = "/linkrels/help"

uri = "/help/appointment"/>

</appointment>





Location: Location: http://royalhope.nhs.uk/slots/1234/appointment

<appointment>



<link rel = "/linkrels/appointment/cancel"


<link rel = "/linkrels/appointment/addAccessory"

uri = "/slots/1234/appointment/tests"/>

<link rel = "self"


<link rel = "/linkrels/appointment/changeTime"

uri = "/workers/mjones/slots?date=20100104@status=open"/>

<link rel = "/linkrels/help"

uri = "/help/appointment"/>

</appointment>


21


<openSlotList>



uri = "/slots/1234"/>

</slot>



uri = "/slots/5678"/>

</slot>

</openSlotList>POST http://<server>/slots/1234





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

From unREST to REST

Software

Transcript of From unREST to REST