What RESTful API is not

What RESTful API is not

Tomasz Skowroński

Agenda

  1. Restful ABC
  2. Methods
  3. Five-Spice Rest
  4. Interface
  5. Levels

Rest?

Rest?

Rest!

Rest!

		/**
		 * Representational State Transfer
		 * 
		 * @author Roy Thomas Fielding
		 * @date 2000
		 */
                Rest.prototype = new ArchitecturalStyle();

Restful ABC

nouns + verbs + adverbs

HTTP methods

GET /balls

DELETE /balls/3

POST /balls

PUT /balls/3

PATCH /balls/3

Rest != CRUD

POST /balls/3/kicks

GET /balls/3/kicks/1

Rest != CRUD2

Read methods

safe, idempotent

Replace methods

not safe, idempotent

Edit methods

not safe, not idempotent

Five-Spice Rest recipe

  1. Client-server
  2. Stateless server
  3. Cache
  4. Layered system
  5. Uniform interface

1-3 Client-Cache-Stateless-Server

Rest != P2P, RS,RDA,EBI

Client-Cache-Stateless-Server

4 Layered System

1-4 CS-SS-CC-LS advantages

  1. Modifiability
  2. Scalability
  3. Visibility (SS, LS)
  4. Reliability (SS)
  5. Simplicity (LS)
  6. Performance (CC)

Rest != SOA

5 Uniform interface

Rest != nice urls

5.1 identify via URIs

Rest != Http + Json

5.2 manipulate via representations

5.3 react via methods and statuses

Rest != ok ? 200 : 500

HTTP statuses

5.4 states and relationships via hypermedia

5 Uniform interface advantages

  1. Visibility
  2. Modifiability
  3. Simplicity

What RESTful API is not

Richardson Maturity Model

Level 0 - No Rest

Level 0 - No Rest

                POST /findBikesByStation?id=1234
                200 [1000,5234,2345]
            
                POST /rentBike/1000
                200

Rest != RPC

Level 1 - Resources

Level 1 - Resources

                POST /stations/1234/bikes
                200 [1000,5234,2345]
            
                POST /bikes/1000/rentBike
                200

Rest != Http transport

Level 2 - HTTP Verbs

Level 2 - HTTP Verbs

                GET /stations/1234/bikes
                200 [1000,5234,2345]
            
                POST /bikes/9999/rents
                200 {"error":"already rented"}

Level 2.5 - HTTP Verbs, Statuses

                GET /stations/1234/bikes
                200 [1000,5234,2345]
            
                POST /bikes/9999/rents
                409
            
                POST /bikes/1000/rents
                301 Location: /bikes/1000/rents/7788

Rest != only resources

Representational State Transfer

Level 3 - Hypermedia

Level 3 - Hypermedia (HATEOAS)

                POST /bikes/1000/rents
                301 Location: /bikes/1000/rents/7788
                  {"content": {"start": "2014-06-23T18:45"},
                  "links":[
                    { "rel": "self", "method": "get", "href": "/bikes/1000/rents/7788"},
                    { "rel": "return", "method": "delete", "href": "/bikes/1000/rents/7788"},
                    { "rel": "bike", "method": "get", "href": "/bikes/1000"}
                  ]}

Level 3 - Hypermedia Controls

                POST /bikes/1000/rents
rel method href
self get /bikes/1000/rents/7788
return delete /bikes/1000/rents/7788
bike get /bikes/1000

Summary

Summary

  1. Client-Cache-Stateless-Server-Layered architectural style

References

  1. http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm
  2. http://design.inf.usi.ch/sites/default/files/talks/SOA2009-REST-Patterns.pdf
  3. http://whatisrest.com/rest_constraints/index
  4. https://blog.apigee.com/detail/api_design_ruminating_over_rest
  5. http://restlet.com/blog/tag/rest-api/
  6. http://www.planetgeek.ch/2012/11/27/rest-fundamentals/
  7. http://www.restapitutorial.com/httpstatuscodes.html
  8. http://4.bp.blogspot.com/_yPMl1jV3I5Q/TKnyMjGudvI/AAAAAAAAAJE/kRdTMZDueEE/s1600/the-letter-r.jpg
  9. https://c1.staticflickr.com/5/4075/4810872878_71e129163f_z.jpg
  10. https://31.media.tumblr.com/tumblr_md0d70S9sy1rsvtbb.jpg
  11. http://s3.amazonaws.com/churchplantmedia-cms/3strand_church_network/rest-stop.jpg
  12. https://dlnmh9ip6v2uc.cloudfront.net/tutorialimages/USB_Guide/USBTypes2.jpg
  13. http://pukahuna.deviantart.com

Thanks