Design a REST API you will love to work with

Talk about common mistakes in REST APIs.

Transcript

1. Design a REST API you will love to work with Posobota 102. (Brněnská) Vladimír Kriška
2. whoami Developer at Keboola currently more on UI/JS than PHP building ETL platform Keboola Connection writing about it at 500.keboola.com Occasional speaker, geek, blogger twitter.com/ujovlado medium.com/@ujovlado ujovlado.com 2
4. State of the APIs? It's 2019 and we're still building (or maintaining) the APIs which are huge PITA to use. Cause: Bad design decisions made (e.g. consuming form-data) Developers are careless about API consumers (e.g. objects everywhere) Developers are lazy (e.g. 400 Bad Request for all things that cannot be processes) 4
6. Fail: Not accepting endpoint w/o trailing / GET /users/ HTTP/1.1 200 OK GET /users HTTP/1.1 500 Internal Server Error Something like your web not working without www part 6
7. But it can be even worse Redirects, they said ... GET /users HTTP/1.1 301 Moved Permanently Location: /users/ POST /users HTTP/1.1 301 Moved Permanently Location: /users/ 7
8. 401 Unauthorized vs. 403 Forbidden It's not the same (obviously) 401 Unauthorized I'm accessing API without valid credentials (token, authorization, etc) 403 Forbidden I'm authorized but not allowed to access speci c endpoint or Rate limiting is in action 8
9. TIP: Return 404 Not Found in some cases Imagine rst user is authenticated. User is allowed to access /pictures/123 (because he uploaded that picture) There's another image with id 456 uploaded by other user Accessing /pictures/456 should return 404 Not Found for the rst user not 403 Forbidden Otherwise we're leaking existence Security issue. 9
10. Fail: 400 Bad Request to all invalid input Malformed JSON is not the same as not sending one parameter 10
11. Tip: Use 422 Unprocessable Entity for validation POST /users { "username": "ujovlado" } HTTP/1.1 422 Unprocessable Entity { "message": "Missing required fields", "errors": [ { "field": "email", "error": "E-mail address is required" } ] } 11
12. Fail: 201 Created with empty body POST /users HTTP/1.1 201 Created I don't know what's that mean Where is resource I just created? Well, I'll get it my way: GET /users ^ That can be prevented 12
13. Tip: Return new resources For creation, return newly created: POST /users HTTP/1.1 201 Created { "username": "ujovlado", "email": "vlado@..." } For updates, return updated resource: PUT /users/ujovlado HTTP/1.1 200 OK { ... 13
14. Tip: 202 Accepted for async resource actions There are some cases when requests action is processed asynchronously Provide meaningful response, so consumer can check processing (if available) 14
15. Tip: Require User-Agent header You'll know who uses your API Automatically populated by browsers 15
16. Tip: Allow browser usage Don't expect only server to server communication (especially not these days when "everything" is moving to client). Accept OPTIONS method. And response with proper headers. OPTIONS / HTTP/1.1 204 No Content Access-Control-Allow-Headers: ... Access-Control-Allow-Methods: ... Access-Control-Allow-Origin: * 16
17. Fail: Everything as object { "data": { "2019-01-01": { "count": 12 }, "2019-01-02": { "count": 30 } } } Do you know what a date means? 17
18. Fail: Even arrays as objects { "data": { "0": { "count": 12 }, "1": { "count": 30 }, "2": { "count": 61 } } } 18
19. Tip: Allow easy processing using map , etc. { "data": [ { "creationDate": "2019-01-01", "count": 12 }, { "creationDate": "2019-01-02", "count": 30 }, ] } 19
20. Fail: Versioning instead of evolution Issuing new endpoint (e.g. /v3 ) is the same like major version of the library. It is less invasive if your APIs are used through client libraries, but still a BC break. 20
21. Next level
22. Include related resources Instead of 2 requests GET /users/ujovlado and GET /users/ujovlado/devices , special parameter is used to include also related resources. GET /users/ujovlado?include=devices { ... "devices": [ {"type": "mobile"}, {"type": "screen"} ] } 22
23. Respect cache-related headers If request is made with header If-Modified-Since: Thu, 05 Feb 2019 15:31:30 GMT you should return data only if resource changed. Otherwise return 304 Not Modify 23
24. HATEOAS (or Hypermedia) Hypermedia As The Engine Of Application State Simply said: Include links to other resources or actions on a resource 24
25. Example GET /users/ujovlado HTTP/1.1 200 OK { "username": "....", "email": "....", "links": { "devices": "https://MY_API/users/ujovlado/devices", "posts": "https://MY_API/users/ujovlado/posts } } 25
26. Tips & Links Spend more time on designing Design your API with respect to some speci cation (e.g. https://jsonapi.org/ is better than nothing) Or use framework which will do it Do not reinvent a wheel, get inspired by highly used APIs (Github API, etc.) For REST APIs, check: https://apisyouwonthate.com/ Try to write simple SPA consuming your API 26
27. Questions?
28. Thank you!