Designing mobile APIs

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

Transcript

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

   View Slide

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

   View Slide

3. View Slide

4. I have a plan!
   

   View Slide

5. View Slide

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

   View Slide

7. Mobile in numbers
   

   View Slide

8. View Slide

9. Web
   App
   Mobile API
   

   View Slide

10. Mobile API
    

    View Slide

11. Example
    

    View Slide

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

    View Slide

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

    View Slide

14. Versioning
    

    View Slide

15. http://fantasy-football.com/api/v1/team/1.json
    

    View Slide

16. http://fantasy-football.com/api/v1/team/1.json
    

    View Slide

17. https://fantasy-football.com/api/v1/team/1.json
    

    View Slide

18. https://fantasy-football.com/api/v1/team/1.json
    

    View Slide

19. https://fantasy-football.com/api/v1/team/1.json
    

    View Slide

20. https://mobile.fantasy-football.com/v1/team/1.json
    

    View Slide

21. https://mobile.fantasy-football.com/v1/team/1.json
    

    View Slide

22. https://mobile.fantasy-football.com/v1/team/1.json
    

    View Slide

23. Content-Types that are acceptable for the response.
    Accept Header
    

    View Slide

24. https://mobile.fantasy-football.com/v1/team/1.json
    

    View Slide

25. Accept: application/json
    https://mobile.fantasy-football.com/v1/team/1.json
    

    View Slide

26. Accept: application/json
    https://mobile.fantasy-football.com/v1/team/1
    

    View Slide

27. Accept: application/json
    https://mobile.fantasy-football.com/v1/team/1
    

    View Slide

28. Accept: application/vnd.football-team.com; version=1,
    application/json
    https://mobile.fantasy-football.com/v1/team/1
    

    View Slide

29. Accept: application/vnd.football-team.com; version=1,
    application/json
    https://mobile.fantasy-football.com/team/1
    

    View Slide

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

    View Slide

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

    View Slide

32. Headers
    

    View Slide

33. User-Agent
    User-Agent: iOS 7.1
    

    View Slide

34. Accept-Language
    Accept-Language: en
    

    View Slide

35. !
    • X-Api-Key
    • X-Push-Notification-Id
    • X-Checksum
    • ….
    Custom
    

    View Slide

36. !
    • X-Api-Key
    • X-Push-Notification-Id
    • X-Checksum
    • ….
    Custom
    

    View Slide

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

    View Slide

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

    View Slide

39. Error responses
    

    View Slide

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
    

    View Slide

41. HTTP Statuses
    http://httpstatus.es/
    

    View Slide

42. Response Body
    {
    “message”: “Invalid api key”
    }
    GET https://mobile.fantasy-football.com/teams/1
    

    View Slide

43. 422 - Unprocessable Entity
    {
    “errors”: {

    “name”: [“Already taken”],
    “budget”: [“Must be more than 0”]
    }
    }
    POST https://mobile.fantasy-football.com/teams/
    

    View Slide

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

    View Slide

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

    View Slide

46. Authentication
    

    View Slide

47. WWW-Authentication
    > WWW-Authenticate: Basic realm=“Fantasy Football”
    !
    < Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
    

    View Slide

48. WWW-Authentication
    > WWW-Authenticate: Digest realm=“Fantasy Football", …
    !
    < Authorization: Digest username=“User", …
    

    View Slide

49. WWW-Authentication
    Authorization: Token token=“7C1100AD4A6D45A6B2E022B”
    

    View Slide

50. View Slide

51. Public
    ~ vs ~
    Private
    

    View Slide

52. OAuth
    ~ vs ~
    Token
    

    View Slide

53. OAuth
    ~ vs ~
    Token
    

    View Slide

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)
    

    View Slide

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

    View Slide

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

    View Slide

57. REST
    

    View Slide

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
    

    View Slide

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”
    

    View Slide

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”
    

    View Slide

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”
    

    View Slide

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 */
    }]
    

    View Slide

63. Paging (1)
    X-Total: 10
    X-Offset: 2
    X-Offset: 3
    

    View Slide

64. Paging (2)
    Link: ; rel="next",
    ; rel=“previous”,
    ; rel=“first”,
    ; rel=“last”
    

    View Slide

65. Paging (3)
    Link: ; rel="next"
    

    View Slide

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

    View Slide

67. Bonus
    

    View Slide

68. Mobile API
    ~ vs ~
    Regular API
    

    View Slide

69. Syncing / Offline
    

    View Slide

70. Postman Chrome plugin
    

    View Slide

71. Good API example
    http://developer.github.com/v3/
    

    View Slide

72. Questions?
    

    View Slide

73. @rstankov
    Thank you :)
    

    View Slide