Designing mobile APIs

Video: https://www.youtube.com/watch?v=Y6LiPJV0EH4

Transcript

1. Radoslav Stankov BlagoevgradConf 2013 30/11/2013 Designing Mobile APIs
2. Radoslav Stankov @rstankov ! ! ! ! http://rstankov.com http://github.com/rstankov
4. I have a plan!
6. 1.Versioning 2.Headers 3.Error responses 4.Authentication 5.REST Agenda
7. Mobile in numbers
9. Web App Mobile API
10. Mobile API
11. Example
12. 1.Versioning 2.Headers 3.Error responses 4.Authentication 5.REST Agenda
13. 1.Versioning! 2.Headers 3.Error responses 4.Authentication 5.REST Agenda
14. Versioning
15. http://fantasy-football.com/api/v1/team/1.json
16. http://fantasy-football.com/api/v1/team/1.json
17. https://fantasy-football.com/api/v1/team/1.json
18. https://fantasy-football.com/api/v1/team/1.json
19. https://fantasy-football.com/api/v1/team/1.json
20. https://mobile.fantasy-football.com/v1/team/1.json
21. https://mobile.fantasy-football.com/v1/team/1.json
22. https://mobile.fantasy-football.com/v1/team/1.json
23. Content-Types that are acceptable for the response. Accept Header
24. https://mobile.fantasy-football.com/v1/team/1.json
25. Accept: application/json https://mobile.fantasy-football.com/v1/team/1.json
26. Accept: application/json https://mobile.fantasy-football.com/v1/team/1
27. Accept: application/json https://mobile.fantasy-football.com/v1/team/1
28. Accept: application/vnd.football-team.com; version=1, application/json https://mobile.fantasy-football.com/v1/team/1
29. Accept: application/vnd.football-team.com; version=1, application/json https://mobile.fantasy-football.com/team/1
30. 1.Versioning! 2.Headers 3.Error responses 4.Authentication 5.REST Agenda
31. 1.Versioning 2.Headers! 3.Error responses 4.Authentication 5.REST Agenda
32. Headers
33. User-Agent User-Agent: iOS 7.1
34. Accept-Language Accept-Language: en
35. ! • X-Api-Key • X-Push-Notification-Id • X-Checksum • …. Custom
36. ! • X-Api-Key • X-Push-Notification-Id • X-Checksum • …. Custom
37. 1.Versioning 2.Headers! 3.Error responses 4.Authentication 5.REST Agenda
38. 1.Versioning 2.Headers 3.Error responses! 4.Authentication 5.REST Agenda
39. Error responses
40. HTTP Statuses Code Description 400 Bad Request 401 Unauthorized 402 Account Is Locked 404 Not Found 405 Method Not Allowed 422 Unprocessable Entity 426 To Many Requests 500 Internal Server Error
41. HTTP Statuses http://httpstatus.es/
42. Response Body { “message”: “Invalid api key” } GET https://mobile.fantasy-football.com/teams/1
43. 422 - Unprocessable Entity { “errors”: {
 “name”: [“Already taken”], “budget”: [“Must be more than 0”] } } POST https://mobile.fantasy-football.com/teams/
44. 1.Versioning 2.Headers 3.Error responses! 4.Authentication 5.REST Agenda
45. 1.Versioning 2.Headers 3.Error responses 4.Authentication! 5.REST Agenda
46. Authentication
47. WWW-Authentication > WWW-Authenticate: Basic realm=“Fantasy Football” ! < Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
48. WWW-Authentication > WWW-Authenticate: Digest realm=“Fantasy Football", … ! < Authorization: Digest username=“User", …
49. WWW-Authentication Authorization: Token token=“7C1100AD4A6D45A6B2E022B”
51. Public ~ vs ~ Private
52. OAuth ~ vs ~ Token
53. OAuth ~ vs ~ Token
54. Tokens Method URL Description POST /token Create new token
 (with login credentials) DELETE /token Delete token HEAD /token Check if token is active PATCH /token Renew a token (if tokens can expire)
55. 1.Versioning 2.Headers 3.Error responses 4.Authentication! 5.REST Agenda
56. 1.Versioning 2.Headers 3.Error responses 4.Authentication 5.REST Agenda
57. REST
58. Teams Method URL Description GET /my/teams Returns all teams POST /my/teams Create new team GET /my/teams/1 Return given team PATCH /my/teams/1 Update given team DELETE /my/teams/1 Delete given team
59. {
 “id”: 1, “name”: “Real Blagoevgrad”,
 “players”: { /* players */ } } POST /my/teams Accept: application/vnd.fantasy-football.com; version=1,application/json
 Authentication: Token token=“0BD8AF0AAB86619” X-Api-Key: “7C1100AD4A6D45A6B2E022B”
60. {
 “id”: 1, “name”: “Real Blagoevgrad”,
 “players”: { /* players */ } } GET /my/teams/1 Accept: application/vnd.fantasy-football.com; version=1,application/json
 Authentication: Token token=“0BD8AF0AAB86619” X-Api-Key: “7C1100AD4A6D45A6B2E022B”
61. {
 “id”: 1, “name”: “Bayern Blagoevgrad”,
 “players”: { /* players */ } } PATCH /my/teams/1 Accept: application/vnd.fantasy-football.com; version=1,application/json
 Authentication: Token token=“0BD8AF0AAB86619” X-Api-Key: “7C1100AD4A6D45A6B2E022B”
62. GET /teams Accept: application/vnd.fantasy-football.com; version=1,application/json
 Authentication: Token token=“0BD8AF0AAB86619” X-Api-Key: “7C1100AD4A6D45A6B2E022B” [{
 “id”: 1, “name”: “Bayern Blagoevgrad”,
 “owner”: { /* owner */ },
 “players”: { /* players */ }, }, { /* other team */ }]
63. Paging (1) X-Total: 10 X-Offset: 2 X-Offset: 3
64. Paging (2) Link: <https://fantasy-football.com/teams/?page=3>; rel="next", <https://fantasy-football.com/teams/?page=1>; rel=“previous”, <https://fantasy-football.com/teams/?page=1>; rel=“first”, <https://fantasy-football.com/teams/?page=100>; rel=“last”
65. Paging (3) Link: <https://fantasy-football.com/teams/?after-id=1213>; rel="next"
66. 1.Versioning 2.Headers 3.Error responses 4.Authentication 5.REST Agenda
67. Bonus
68. Mobile API ~ vs ~ Regular API
69. Syncing / Offline
70. Postman Chrome plugin
71. Good API example http://developer.github.com/v3/
72. Questions?
73. @rstankov Thank you :)