REST != REST

CLAUDIO ALTAMURA Software Architect and Software Developer @AltamuraClaudio

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

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

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

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

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

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

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?

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

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

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

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

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

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

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

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

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

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

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

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" }] }

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

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

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

QUESTIONS

LINKS REST API Design Principles Standards APIs Frameworks

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/

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

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

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