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

REST not equals REST

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.

6c08c67898c066cb61225eeb965275e6?s=128

Claudio Altamura

December 12, 2019
Tweet

Transcript

  1. REST != REST

  2. CLAUDIO ALTAMURA Software Architect and Software Developer @AltamuraClaudio

  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
  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
  5. EXAMPLES spinal-case Jira GET /rest/api/2/application-propert snake_case Gitlab GET /users/:id/custom_attributes

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

    /api/v1/users.getAvatar
  7. URI STRUCTURE foo://example.com:8042/over/there?name=ferret#nose \_/ \______________/\_________/ \_________/ \__/ | | |

    | | scheme authority path query fragment https://www.ietf.org/rfc/rfc3986.txt
  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
  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?
  10. HTTP METHODS 1 returns a list returns a single resource

    creates a resource GET /accounts GET /accounts/1 POST /accounts
  11. HTTP METHODS 2 updates a resource modi es a resource

    deletes a resource PUT /accounts/1 PATCH /accounts/1 DELETE /accounts/1
  12. HTTP STATUS CODES SUCCESS CODES code comment 200 OK 201

    CREATED 202 ACCEPTED 204 NO CONTENT 206 PARTIAL CONTENT
  13. CLIENT ERRORS code comment 400 BAD REQUEST 401 UNAUTHORIZED 403

    FORBIDDEN 404 NOT FOUND
  14. CLIENT ERRORS 2 code comment 405 METHOD NOT ALLOWED 406

    NOT ACCEPTABLE 409 CONFLICT 410 GONE 429 TOO MANY REQUESTS
  15. SERVER ERRORS code comment 500 INTERNAL SERVER ERROR 503 SERVICE

    UNAVAILABLE 504 GATEWAY TIMEOUT
  16. REST MATURITY MODEL https://restfulapi.net/richardson-maturity-model/

  17. LEVEL 0 single URI read & write operations SOAP-based payloads

    POST http://myws.com/api/accou
  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
  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
  20. LEVEL 3 https://en.wikipedia.org/wiki/HATEOAS https://en.wikipedia.org/wiki/Hypertext_Application_Language HATEOAS Spring example

  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" }] }
  22. JSON API Spec https://jsonapi.org/format/

  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
  24. BAD PATCH for update ??? https://jsonapi.org/format/#crud-updating https://jsonapi.org/format/#crud-updating-resource-attributes

  25. QUESTIONS

  26. LINKS REST API Design Principles Standards APIs Frameworks

  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/

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