REST not equals REST

REST is a defacto standard and every developer implements REST APIs in a different way. In this talk I'll show best practices and standards around REST. I hope that helps you to build APIs with higher developer experience.

Transcript

1. REST != REST
   

   View Slide

2. CLAUDIO ALTAMURA
   Software Architect and Software Developer
   @AltamuraClaudio
   

   View Slide

3. DEVELOPER EXPERIENCE
   Why does it matter?
   users of your technology are happier
   promote it more
   stay longer when the product
   https://hackernoon.com/the-best-practices-for-a-great-developer-experience-dx-9036834382b0
   

   View Slide

4. RESOURCE NAMING
   Use nouns to represent resources
   plural
   spinal-case or snake_case
   hierarchical relationships with slash
   GET /accounts/1234
   GET /accounts/{id}/settings
   

   View Slide

5. EXAMPLES
   spinal-case Jira
   GET /rest/api/2/application-propert
   snake_case Gitlab
   GET /users/:id/custom_attributes
   

   View Slide

6. SPECIAL CASES
   lower-case Kubernetes
   POST /api/v1/namespaces/{ns}/limitran
   ??? case Rocket.Chat
   GET /api/v1/users.getAvatar
   

   View Slide

7. URI STRUCTURE
   foo://example.com:8042/over/there?name=ferret#nose
   \_/ \______________/\_________/ \_________/ \__/
   | | | | |
   scheme authority path query fragment
   https://www.ietf.org/rfc/rfc3986.txt
   

   View Slide

8. EXAMPLES
   JIRA
   Gitlab
   Kubernetes
   Rocket.Chat
   GET http://www.example.com/jira/rest/api/2/u
   GET https://gitlab.example.com/api/v4/projec
   GET https://example.com/api/v1/pods
   POST http://localhost:3000/api/v1/users.crea
   

   View Slide

9. SPECIAL CASES
   Net ix
   GitHub Accept Header
   application/vnd.github.v3+json
   GET https://api.github.com/repos/me/repo/readme
   GET http://api.netflix.com/catalog/titles/series/70023522?
   

   View Slide

10. HTTP METHODS 1
    returns a list
    returns a single resource
    creates a resource
    GET /accounts
    GET /accounts/1
    POST /accounts
    

    View Slide

11. HTTP METHODS 2
    updates a resource
    modi es a resource
    deletes a resource
    PUT /accounts/1
    PATCH /accounts/1
    DELETE /accounts/1
    

    View Slide

12. HTTP STATUS CODES
    SUCCESS CODES
    code comment
    200 OK
    201 CREATED
    202 ACCEPTED
    204 NO CONTENT
    206 PARTIAL CONTENT
    

    View Slide

13. CLIENT ERRORS
    code comment
    400 BAD REQUEST
    401 UNAUTHORIZED
    403 FORBIDDEN
    404 NOT FOUND
    

    View Slide

14. CLIENT ERRORS 2
    code comment
    405 METHOD NOT ALLOWED
    406 NOT ACCEPTABLE
    409 CONFLICT
    410 GONE
    429 TOO MANY REQUESTS
    

    View Slide

15. SERVER ERRORS
    code comment
    500 INTERNAL SERVER ERROR
    503 SERVICE UNAVAILABLE
    504 GATEWAY TIMEOUT
    

    View Slide

16. REST MATURITY MODEL
    https://restfulapi.net/richardson-maturity-model/
    

    View Slide

17. LEVEL 0
    single URI
    read & write operations
    SOAP-based payloads
    POST http://myws.com/api/accou
    

    View Slide

18. LEVEL 1
    many URIs
    only a single HTTP verb – generally HTTP POST
    POST http://myws.com/api/createAccount
    POST http://myws.com/api/updateAccount
    POST http://myws.com/api/deleteAccount
    

    View Slide

19. LEVEL 2
    URI for every resource
    using HTTP Verbs, e.g. GET, POST, PUT, DELETE
    GET http://myws.com/api/accounts
    POST http://myws.com/api/accounts/2
    PUT http://myws.com/api/accounts/2
    DELETE http://myws.com/api/accounts/2
    

    View Slide

20. LEVEL 3
    https://en.wikipedia.org/wiki/HATEOAS
    https://en.wikipedia.org/wiki/Hypertext_Application_Language
    HATEOAS Spring example
    

    View Slide

21. HATEOAS LINKS WITH METHODS
    Paypals HATEOAS links
    {
    "links": [{
    "href": "https://api.paypal.com/v1/payments/sale/36C38912MN9658832",
    "rel": "self",
    "method": "GET"
    }, {
    "href": "https://api.paypal.com/v1/payments/sale/36C38912MN9658832/refund"
    "rel": "refund",
    "method": "POST"
    }, {
    "href": "https://api.paypal.com/v1/payments/payment/PAY-5YK922393D847794YK
    "rel": "parent_payment",
    "method": "GET"
    }]
    }
    

    View Slide

22. JSON API
    Spec https://jsonapi.org/format/
    

    View Slide

23. GOOD
    Document structure
    Resource Links
    Content Location
    https://jsonapi.org/format/#document-top-level
    https://jsonapi.org/format/#error-objects
    https://jsonapi.org/format/#document-resource-object-links
    https://rancher-ha.prod.hhrz1.de.etracker.com/v3/project/c-jsx9j:p-d6s89/
    https://jsonapi.org/format/#crud-creating-responses-201
    

    View Slide

24. BAD
    PATCH for update ???
    https://jsonapi.org/format/#crud-updating
    https://jsonapi.org/format/#crud-updating-resource-attributes
    

    View Slide

25. QUESTIONS
    

    View Slide

26. LINKS
    REST API Design Principles
    Standards
    APIs
    Frameworks
    

    View Slide

27. REST API DESIGN PRINCIPLES
    https://blog.octo.com/design-a-rest-api/
    https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-
    conventions.md
    https://blog.restcase.com/5-basic-rest-api-design-guidelines/
    https://restfulapi.net/
    

    View Slide

28. STANDARDS
    JSON API Spec
    HTTP
    HTTP Status Codes
    URI Syntax
    HATEOAS
    HAL
    https://jsonapi.org/
    https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol
    https://en.wikipedia.org/wiki/List_of_HTTP_status_codes
    https://www.ietf.org/rfc/rfc3986.txt
    https://en.wikipedia.org/wiki/HATEOAS
    https://en.wikipedia.org/wiki/Hypertext_Application_Language
    https://tools.ietf.org/html/draft-kelly-json-hal-00
    

    View Slide

29. APIS
    Kubernetes
    Gitlab
    Rocket.Chat
    Rancher
    GitHub
    Twitter
    https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.16/
    https://docs.gitlab.com/ee/api/api_resources.html
    https://rocket.chat/docs/developer-guides/rest-api/
    https://rancher.com/docs/rancher/v2.x/en/api/
    https://developer.github.com/v3/
    https://developer.twitter.com/en/docs/tweets/post-and-engage/api-reference/get-
    statuses-retweets-id
    

    View Slide

30. FRAMEWORKS
    Spring HATEOAS
    Spring with JSON API (Karthasis)
    https://docs.spring.io/spring-hateoas/docs/1.0.1.RELEASE/reference/html/
    https://www.baeldung.com/json-api-java-spring-web-app
    

    View Slide