Designing mobile APIs

Transcript

1. Radoslav Stankov BlagoevgradConf 2013 30/11/2013 Designing Mobile APIs

2. Radoslav Stankov @rstankov ! ! ! ! http://rstankov.com http://github.com/rstankov

3. None

4. I have a plan!

5. None

6. 1.Versioning 2.Headers 3.Error responses 4.Authentication 5.REST Agenda

7. Mobile in numbers

8. None

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”

50. None

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 :)