Designing mobile APIs

Designing mobile APIs

7a0e72a6f55811246bb5d9a946fd2e49?s=128

Radoslav Stankov

November 30, 2013
Tweet

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