All about APIs

Presentation about best practices on RESTful APIs, created by Diogo Laginha Machado & Ricardo Vitorino:

- Basic Concepts
- Challenges
- API design
- Hypermedia
- Versioning
- Documentation

Transcript

1. All about APIs >  GET            /presentations/apis >  Accept:    application/vnd.apple.keynote  version=1.0 <  Date:        Sat,  23  Mar  2013 <  Content: {  authors:  [  Diogo  Laginha,  Ricardo  Vitorino  ],  awesome:  true }
2. The Basics
3. What is REST? 3 “It's about transferring representations of the state... of resources” Steve Klabnik
4. What’s a resource? - Sources of information (documents or services) - Any interaction with a RESTful API is an interaction with a resource
5. RESTful APIs 5 A set of URIs that map entities to endpoints. resource resource resource URI URI URI
6. Challenges
7. Typical scenario 7
8. Typical scenario 7 Web application
9. The problem 8 Don’t give your users sh_t work!
10. Challenges 9 - API discovery - Resource browsing - Resource versioning - Documentation
11. API design
12. Designing APIs 11
13. Resources 12 - Must be nouns!
14. Resources 12 - Must be nouns! - Examples: /articles/ /authors/ /books/ /presentations/
15. Actions 13 The way to perform an action in a RESTful API is to use HTTP verbs (request methods)
16. Actions 14 HTTP methods:
17. Actions 14 HTTP methods: • GET
18. Actions 14 HTTP methods: • GET • HEAD
19. Actions 14 HTTP methods: • GET • HEAD • OPTIONS
20. Actions 14 HTTP methods: • GET • HEAD • OPTIONS • POST
21. Actions 14 HTTP methods: • GET • HEAD • OPTIONS • POST • PUT
22. Actions 14 HTTP methods: • GET • HEAD • OPTIONS • POST • PUT • PATCH
23. Actions 14 HTTP methods: • GET • HEAD • OPTIONS • POST • PUT • PATCH • DELETE
24. Actions 15 Don’t include the verb in the resource /presentations/delete/1
25. Actions 16 Use the DELETE method instead /presentations/1
26. Representation 17 /articles/ - It doesn't include the format
27. Representation 17 /articles/ - It doesn't include the format - A given resource can have different representations (XML, JSON, …)
28. Representation 18 - Don’t do this GET  /presentations/ format=json
29. - Don’t do this either GET  /presentations.json Representation 19
30. - Use the Accept Header Representation GET  /presentations/ Accept:  application/json 20
31. 21 Resources are mapped to URLs Actions are mapped to verbs The rest goes in the headers Resources are mapped to URIs Actions are mapped to verbs The rest goes in the headers
32. Request headers: - Accept-Language - User-Agent - Authentication - ... Other Headers 22
33. Response headers: - Link - Content-Type - Status - ... Other Headers 23
34. Hypermedia
35. Hyper-whaa?! 25
36. Hyper-whaa?! 25 Ignore this, we’re talking about hyperlinks here
37. 26 You want to say “Happy Birthday” on some social network. What if…
38. 26 You want to say “Happy Birthday” on some social network. Option A Go directly to friend’s page and post. What if…
39. 26 You want to say “Happy Birthday” on some social network. Option A Go directly to friend’s page and post. Option B Go to Homepage > search friend > post. What if…
40. 26 You want to say “Happy Birthday” on some social network. Option A Go directly to friend’s page and post. Option B Go to Homepage > search friend > post. What if…
41. 27 Then… Why shouldn’t you do the same for APIs?
42. 27 Then… Why shouldn’t you do the same for APIs? >  GET        /apis <  Content:    apis:  [    {        path:  "/presentations/",            description:  "Barcamp  presentations"        },        {        path:  "/users/",            description:  "Who  signed  up  for  Barcamp"        },    ]
43. 28 That’s hypermedia!
44. 28 That’s hypermedia! Actually, it’s called HATEOAS.
45. 28 That’s hypermedia! Actually, it’s called HATEOAS. Hypermedia as the Engine of Application State
46. 28 That’s hypermedia! Actually, it’s called HATEOAS. Hypermedia as the Engine of Application State -Single endpoint for the resource
47. 28 That’s hypermedia! Actually, it’s called HATEOAS. Hypermedia as the Engine of Application State -Single endpoint for the resource -All actions discovered by inspecting resource
48. 29 HATEOAS Get a certain keynote:    presentation:  { id:      1337, name:      "All  About  APIs", date:      "2013-­‐03-­‐23", authors:  {    path:      "/presentations/1337/authors/",        description:  "Keynote’s  authors", }    }
49. 29 HATEOAS Get a certain keynote:    presentation:  { id:      1337, name:      "All  About  APIs", date:      "2013-­‐03-­‐23", authors:  {    path:      "/presentations/1337/authors/",        description:  "Keynote’s  authors", }    } We know what to do next ☺
50. 30 HATEOAS Get all the keynotes:    presentations:  [ {...},    ... {...}    ], Meta:  { total:  100, paginated_objects:  25, next_page:  "/presentations?offset=25" }
51. 30 HATEOAS Get all the keynotes:    presentations:  [ {...},    ... {...}    ], Meta:  { total:  100, paginated_objects:  25, next_page:  "/presentations?offset=25" } }25 presentations
52. 30 HATEOAS Get all the keynotes:    presentations:  [ {...},    ... {...}    ], Meta:  { total:  100, paginated_objects:  25, next_page:  "/presentations?offset=25" } }25 presentations Where to get some more
53. Versioning
54. - Version a resource representation, not the API First of all 32
55. - Version a resource representation, not the API - Add a new version when the changes in the resource representation are non- backward compatible First of all 32
56. - Don’t do this 33 Versioning GET  /presentations/v1/
57. - Don’t do this - Resources should only include nouns! 33 Versioning GET  /presentations/v1/
58. - Don’t do this - Resources should only include nouns! - Besides, it’s ugly 33 Versioning GET  /presentations/v1/
59. 34 Versioning - Use the Accept Header GET  /presentations/ Accept:  version=1
60. Documentation
61. Use case If you want your application to use some awesome APIs... 36
62. Read the docs ... you need to read their manual. 37
63. Read the docs ... you need to read their manual. 37
64. Read the docs ... you need to read their manual. 37
65. Wouldn’t it be nicer to get some hands-on? Idea 38 DELETE POST PUT GET
66. Swagger https://developers.helloreverb.com/swagger/
67. Swagger 40 - Document your API with style
68. Swagger 40 - Document your API with style - No more dull .doc files or ugly pages
69. Swagger 40 - Document your API with style - No more dull .doc files or ugly pages - Give your users a playground
70. Benefits 41 API discovery:
71. Benefits 42 Check the result schema with actual data:
72. Benefits 43 Swagger has a family:
73. Requires work, though 44
74. @OST 45 - API discovery - Documentation - Versioning - Browsing
75. References - http://www.apievangelist.com/ - http://publish.luisrei.com/articles/rest.html - http://blog.steveklabnik.com - http://www.designinghypermediaapis.com - https://twitter.com/hypermediaapis - https://developers.helloreverb.com/swagger/ - http://laginha.github.com/yard/ 46
76. GET /questions/ 47