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