Upgrade to Pro — share decks privately, control downloads, hide ads and more …

REST my dongle #kreait-dev-days

REST my dongle #kreait-dev-days

REST best practices, HAL, HATEOAS

Armen Mkrtchyan

June 05, 2015
Tweet

More Decks by Armen Mkrtchyan

Other Decks in Programming

Transcript

  1. Logitech R400

    View full-size slide

  2. [
    {
    "id": 1,
    "content": "Slide 1"
    },
    {
    "id": 2,
    "content": "Slide 2"
    },
    ]

    View full-size slide

  3. GET /slide/1

    View full-size slide

  4. {
    "id": 1,
    "content": "Slide 1",
    "background": "white",
    "text": "#031337"
    }

    View full-size slide

  5. Verb Method
    GET /slides Get list of slides
    C POST /slides Create new slide
    R GET /slides/:id Get specific slide
    U PUT /slides/:id Update slide
    D DELETE /slides/:id Delete slide

    View full-size slide

  6. Next
    Previous

    View full-size slide

  7. 1. GET /slides
    2. Remember IDs
    3. Figure out index
    4. index++
    5. GET /slides/2

    View full-size slide

  8. GET /slides/1/next
    GET /nextSlide/1

    View full-size slide

  9. REST Maturity Model

    View full-size slide

  10. HATEOAS
    (Hypertext As The Engine Of Application State)
    Level 3: Hypermedia
    HAL
    (Hypertext Application Language)

    View full-size slide

  11. {
    "id": 5,
    "content": "Slide 1",
    "background": "white",
    "text": "#031337"
    "_links": {
    "self": { "href": "/slides/5" },
    "prev": { "href": "/slides/4" },
    "next": { "href": "/slides/6" },
    "first": { "href": "/slides/1" },
    "last": { "href": "/slides/12" }
    }
    }

    View full-size slide

  12. HAL + JSON
    http://stateless.co/hal_specification.html

    View full-size slide

  13. R(B)EST practices

    View full-size slide

  14. 1. Do not use verbs
    /getAllSlides
    /createNewSlide
    /deleteAllBlackSlides
    GET /slides
    POST /slides
    DELETE /slides?filter=black

    View full-size slide

  15. 2. GET method should
    NEVER alter the state
    GET /slide/1?action=disable
    POST /slides/1/disable
    or
    PUT /slides/1/disable

    View full-size slide

  16. 3. Use plural nouns
    /slide
    /slides

    View full-size slide

  17. 4. Use sub-resources
    for relations
    GET /animationsForSlide/1
    DELETE /animationsFromSlide/1/2
    GET /slides/1/animations/
    DELETE /slides/1/animations/3

    View full-size slide

  18. 5. Use HTTP headers for
    serialization formats
    Content-type: application/vnd+com.kreait.slide+json

    View full-size slide

  19. 6. Use HAL
    {
    "id": 1,
    "content": "Slide 1",
    "background": "white",
    "text": "#031337"
    "_links": {
    "self": { "href": "/slides/1" },
    "next": { "href": "/slides/2" }
    }
    }

    View full-size slide

  20. 7. Filtering, Sorting,
    field selection and paging
    Filter GET /slides?background=white
    Sort GET /slides?sort=-title,+length
    Limit Fields GET /slides?fields=id,title
    Pagination GET /slides?offset=10&limit=5

    View full-size slide

  21. 8. Version your API
    In URL: /api/v1/slides

    View full-size slide

  22. 9. Handle Errors with
    HTTP status codes
    http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html
    and
    https://github.com/joho/7XX-rfc
    Errors in vnd.error format
    (https://github.com/blongden/vnd.error)
    or at least something consistent

    View full-size slide

  23. 10. Allow overriding
    HTTP method
    X-HTTP-Method-Override: PUT

    View full-size slide

  24. Dongle included
    Thanks!

    View full-size slide