A bird's eye view on API development - the live action version

In this talk Frederick is going to prove he is more then just a pretty face! The talk will cover the basics of api design and will move on to more advanced topics like authentication. The talk itself is based on his blogpost (blog.madewithlove.be/post/birdseye-view-on-api/) but will delve deeper into the topics discussed there. The talk is language agnostic, so even if you're into some obscure programming language you can still adapt the techniques discussed.

Transcript

1. #purple
2. API DEVELOPMENT
3. WHO ? Frederick Vanbrabant Software engineer madewithlove
5. phpantwerp slide
6. { "id": 1, "title": "7 Things You Should NEVER Do to a potato", "subtitle": "you will never believe nr 4", "body": "lorem ipsum dolor kebab", "comments": [{ "id": 1, "body": "woah this changed my life" }, { "id": 2, "body": "I will never look at dem taters in the same way" }] } GET /getblogpost/1
7. Why is this not so great ? Url is kinda structure less What if we get loads of articles? What if we get loads of comments? Damn we need to write documentation Is this secure?
8. GET /getblogposts/1 Let's look at that endpoint HTTP verb Endpoint
9. HTTP verbs
10. HTTP verbs HTTP != CRUD
11. HTTP verbs Verb Return HTTP Code POST 201 Sends a payload to the server, Returns an empty body.
12. HTTP verbs Verb Return HTTP Code POST 201 POST /posts { "title": "Why cheese is better then real friends", "body": "People only stand in the way of you and your cheese!" } Post body
13. HTTP verbs Verb Return HTTP Code GET 200 Does not send a payload Returns a collection of or a single resource
14. HTTP verbs Verb Return HTTP Code GET 200 POST /posts/2 { "title": "How to fake your own death", "body": "You can buy cheese with the insurance money!" } Return body
15. HTTP verbs Verb Return HTTP Code PUT 200 Updates a resource (needs the entire object) Returns an empty body.
16. HTTP verbs Verb Return HTTP Code PUT 200 POST /posts { "title": "Help I'm stuck in a keynote making factory", "body": "Send cheese!" } Put body
17. HTTP verbs Verb Return HTTP Code PATCH 200 Accepts instructions to update the resource Returns the resource
18. Wait what? Accepts instructions to update the resource returns the resource PATCH /artists/kanye/ [ { "op": "replace", "path": "/taylorwift/insults", "value": 2 }, ]
19. Wait what? Accepts instructions to update the resource returns the resource PATCH /artists/kanye/albums/lifeofpablo [ {"taylor_swift_insults" : "2"} ] Content-Type: application/partial-update-json
20. HTTP verbs Verb Return HTTP Code DELETE 200 Removed the resource Returns an empty body.
21. HTTP verbs Verb Return HTTP Code DELETE 200 DELETE /posts/1
22. HTTP CODE
24. HTTP CODE Range 1XX - Information Code What it means 100 continue 101 Switching Protocols 102 Processing
25. HTTP CODE Range 2XX - Success Code What it means 200 Ok 201 Created 202 Accepted
26. HTTP CODE Range 3XX - Redirection Code What it means 301 Moved 300 Multiple Choices
27. HTTP CODE Range 4XX - Client error Code What it means 400 Bad Request 401 Unauthorized 404 Not found
28. HTTP CODE Range 5XX - Server error Code What it means 500 Internal Server Error 503 Service Unavailable 504 Gateway Timeout
29. What about the endpoint GET /getblogposts/1
30. What about the endpoint GET /posts/1 Nouns are good, verbs are bad Use plurals
31. What about the endpoint Endpoint structure <> database structure Get /book/553 { "title": "Coping with cheese addiction", "writer": "M.ouse", "price": 14.55 } Books Writers Prices
32. What about the endpoint GET /posts/1 GET /posts/1/comments GET /posts/1/comments/15
33. What about the endpoint GET /posts GET /posts/slugs-are-allowed
34. What about the endpoint GET users/4b3403665fea6/posts/4b340550242239
35. We still 200 ?
36. Let's check out that body? { "id": 1, "title": "7 Things You Should NEVER Do to a potato", "subtitle": "you will never believe nr 4", "body": "lorem ipsum dolor kebab", "comments": [{ "id": 1, "body": "woah this changed my life" }, { "id": 2, "body": "I will never look at dem taters in the same way" }] }
37. Let's use a standard Battle tested and growing up to be the standard
38. { "count": 87, "next": "http://swapi.co/api/people/?page=2", "previous": null, "results": [ { "name": "Luke Skywalker", "height": "172", "mass": "77", "hair_color": "blond", "skin_color": "fair", "eye_color": "blue", "birth_year": "19BBY", "gender": "male", "homeworld": "http://swapi.co/api/planets/1/", "films": [ "http://swapi.co/api/films/6/", "http://swapi.co/api/films/3/", "http://swapi.co/api/films/2/", "http://swapi.co/api/films/1/", "http://swapi.co/api/films/7/" ], "species": [ "http://swapi.co/api/species/1/" ], "vehicles": [ "http://swapi.co/api/vehicles/14/", "http://swapi.co/api/vehicles/30/" ], "starships": [ "http://swapi.co/api/starships/12/", "http://swapi.co/api/starships/22/" ], "created": "2014-12-09T13:50:51.644000Z", "edited": "2014-12-20T21:17:56.891000Z", "url": "http://swapi.co/api/people/1/"
39. { "count": 87, "next": "http://swapi.co/api/people/?page=3", "previous": "http://swapi.co/api/people/?page=1", "results": [ .... ] } Links ? page-based
40. { "count": 30, "next": "http://swapi.co/api/people/?offset=60&limit=30", "previous": "http://swapi.co/api/people/?offset=0&limit=30", "results": [ .... ] } Links ? offset-based
41. { "count": 87, "next": "http://swapi.co/api/people/?cursor=1374004777531007833", "previous": "http://swapi.co/api/people/?cursor=2627305797328905258", "results": [ .... ] } Links ? cursor-based
42. { "name": "Luke Skywalker", "height": "172", "mass": "77", "hair_color": "blond", "skin_color": "fair", "eye_color": "blue", "birth_year": "19BBY", "gender": "male", "homeworld": "http://swapi.co/api/planets/1/", "films": [ "http://swapi.co/api/films/6/", "http://swapi.co/api/films/3/", "http://swapi.co/api/films/2/", "http://swapi.co/api/films/1/", "http://swapi.co/api/films/7/" ], "species": [ "http://swapi.co/api/species/1/" ], "vehicles": [ "http://swapi.co/api/vehicles/14/", "http://swapi.co/api/vehicles/30/" ], "starships": [ "http://swapi.co/api/starships/12/", "http://swapi.co/api/starships/22/" ], "created": "2014-12-09T13:50:51.644000Z", "edited": "2014-12-20T21:17:56.891000Z", "url": "http://swapi.co/api/people/1/" }
43. Wait I can't have nested- resources?
44. Wait I can't have nested- resources? This is not really HTTP now is it ?
45. Think about how you surf the web That's pretty nice right ?
46. HATEOAS Hypermedia as the Engine of Application State
47. HATEOAS Hypermedia as the Engine of Application State { "name": "Boba Fett", "height": "183", "mass": "78.2", "hair_color": "black", "skin_color": "fair", "eye_color": "brown", "birth_year": "31.5BBY", "gender": "male", "homeworld": "http://swapi.co/api/planets/10/", "films": [ "http://swapi.co/api/films/5/", "http://swapi.co/api/films/3/", "http://swapi.co/api/films/2/" ], "species": [ "http://swapi.co/api/species/1/" ], "vehicles": [], "starships": [ "http://swapi.co/api/starships/21/" ], "created": "2014-12-15T12:49:32.457000Z", "edited": "2014-12-20T21:17:50.349000Z", "url": "http://swapi.co/api/people/22/" }
48. HATEOAS "I'm not going to make 500 calls just to get some comments"
49. HATEOAS "I'm not going to make 500 calls just to get some comments" GET /articles/1/comments GET /articles/1/comments/2,4,6,8
50. HATEOAS "Can't you just add the resources to the url?" GET /articles/1?include=comments,likes
51. AUTH
52. AUTH
53. AUTH - HTTP Basic - JWT - OAuth 2.0
54. HTTP Basic - Super easy - Not super safe
55. JWT (Json web tokens) - No database hassle - Needs some knowledge
56. JWT (Json web tokens) Server Client make new calls with the token Return token Send credentials
57. OAuth2 - Very secure and very flexible - Can be daunting to setup
58. OAuth2 Server Client make new calls with the token Return token + Refresh token Send credentials
59. OAuth2 Server Client make new calls with the token Return token + Refresh token Send refresh token
60. Random TIPS A GOOD API DOES NOT NEED TO BE REST
61. Random TIPS LOOK AT THE USER FIRST, NOT THE TECH
62. Random TIPS TYPE CAST YOUR RETURN VALUES
63. Random TIPS CONSISTENCY IS KING
64. Random TIPS TEST YOUR ENDPOINTS
65. Random TIPS NEVER TRUST YOUR USERS
66. Random TIPS Use PHP? Laravel: https://github.com/dingo/api Vanilla: https://thephpleague.com Use Python? Django: http://www.django-rest-framework.org
67. Random TIPS Want to know more? This talks in text form: https://blog.madewithlove.be/post/birdseye-view-on-api Phil Sturgeon's book: https://leanpub.com/build-apis-you-wont-hate Great O'Reily book RESTful Web APIs: http://shop.oreilly.com/product/0636920028468.do
68. Questions! Twitter: TheEdonian
69. THANKS !