Mobile API. Design & Techniques.

Designing a web API is hard, designing a mobile API is even harder. With heavy constraints such as bandwidth, latency and CPU power, developing a mobile API is a challenge for the service provider and the application developer. As mobile devices become ubiquitous and connected, offering the best user experience in mobile application is crucial; optimizing the network is an important part of it.

In this talk we'll cover the challenges of designing a mobile API as well as innovative solutions and best practices that can be used by the service provider. We'll share our broad experience in developing connected mobile apps.

Transcript

1. Mobile API
   Design & Techniques.
   Fred Brunel
   CTO
   Wednesday, 29 February, 12
   

   View Slide

2. Wednesday, 29 February, 12
   

   View Slide

3. Wednesday, 29 February, 12
   

   View Slide

4. Wednesday, 29 February, 12
   

   View Slide

5. Why?
   Wednesday, 29 February, 12
   

   View Slide

6. Though for CPU power
   Though for bandwidth
   Lazy designed.
   Too close to database.
   Wednesday, 29 February, 12
   

   View Slide

7. A mobile device is
   Low powered
   Low bandwidth
   Runs on battery!
   Wednesday, 29 February, 12
   

   View Slide

8. A the network is the
   weak link.
   Wednesday, 29 February, 12
   

   View Slide

9. Network conditions
   change in real-time.
   Wednesday, 29 February, 12
   

   View Slide

10. We want to keep the
    best user experience
    at all time.
    Nobody wants an
    unresponsive app.
    Wednesday, 29 February, 12
    

    View Slide

11. The features of an
    API has a huge
    impact on
    performances.
    Wednesday, 29 February, 12
    

    View Slide

12. An API is a contract
    that dictates what
    can or cannot be
    done (directly).
    Wednesday, 29 February, 12
    

    View Slide

13. When the API is too
    lazy, or incomplete;
    the burden is put on
    the mobile app.
    Wednesday, 29 February, 12
    

    View Slide

14. Any workaround put
    a stress on the
    mobile app to use
    too much network.
    Wednesday, 29 February, 12
    

    View Slide

15. API = User Interface.
    Should be simple and
    get the job done. Fast.
    Wednesday, 29 February, 12
    

    View Slide

16. Landlord Report.
    Wednesday, 29 February, 12
    

    View Slide

17. Simple
    Standard Complete
    Wednesday, 29 February, 12
    

    View Slide

18. Simple
    Standard Complete
    SOAP
    XML-RPC
    WS-*
    Pure REST
    Wednesday, 29 February, 12
    

    View Slide

19. Simple
    Complete
    Wednesday, 29 February, 12
    

    View Slide

20. Trust the OSI model.
    Works everywhere.
    And it’s plenty enough.
    http://en.wikipedia.org/wiki/OSI_model
    Wednesday, 29 February, 12
    

    View Slide

21. REST-ish API + JSON
    Pure REST is a nice to
    have but not a goal.
    Wednesday, 29 February, 12
    

    View Slide

22. GET/POST + Action +
    Params is fine.
    PUT/DELETE are nice
    to have.
    Wednesday, 29 February, 12
    

    View Slide

23. Twitter is also REST-ish
    POST statuses/create
    POST statuses/destroy/:id
    POST statuses/update
    Wednesday, 29 February, 12
    

    View Slide

24. REST put an emphasis
    on actions applied to
    resources; but the
    issue is the
    representation.
    Wednesday, 29 February, 12
    

    View Slide

25. Simplify the life of the
    implementor.
    Be pragmatic.
    Wednesday, 29 February, 12
    

    View Slide

26. When designing your
    API payloads, pay
    attention to
    consistency and
    completeness.
    Wednesday, 29 February, 12
    

    View Slide

27. Consistency means
    developer know what
    to expect.
    Principle of least
    astonishment.
    Wednesday, 29 February, 12
    

    View Slide

28. Completeness means
    less roundtrips.
    Wednesday, 29 February, 12
    

    View Slide

29. HTTP latency on 3G
    ~ 1 second.
    Every request count.
    Wednesday, 29 February, 12
    

    View Slide

30. API is NOT a CRUD
    interface to your SQL
    database.
    It’s a facade.
    Wednesday, 29 February, 12
    

    View Slide

31. Database
    Facade
    API
    App
    Data
    Representation
    Raw Data
    Display
    Wednesday, 29 February, 12
    

    View Slide

32. The facade answer to
    high-level questions.
    Think services, not
    objects and methods.
    Wednesday, 29 February, 12
    

    View Slide

33. So, how do we start
    from here?
    Wednesday, 29 February, 12
    

    View Slide

34. Most of the time, a
    mobile API will be use
    to get information to
    be displayed on a
    screen.
    Wednesday, 29 February, 12
    

    View Slide

35. Reverse Design.
    Start from the UI
    Not the data
    Wednesday, 29 February, 12
    

    View Slide

36. 1. Think screens
    2.Entities to display
    3.Design entity models
    4.Design services
    Wednesday, 29 February, 12
    

    View Slide

37. Wednesday, 29 February, 12
    

    View Slide

38. ID
    Title
    Town
    Country
    Rating
    Thumbnail URL
    Geocode
    Website
    Email
    Description
    Wednesday, 29 February, 12
    

    View Slide

39. Then, format the
    representation to be as
    efficient as possible.
    Wednesday, 29 February, 12
    

    View Slide

40. Each JSON entity
    should have the same
    consistent
    representation.
    Wednesday, 29 February, 12
    

    View Slide

41. "person": {
    "id": 1234,
    "name": "Fred",
    "lastname": "Brunel",
    "company": "WhereCloud"
    }
    Wednesday, 29 February, 12
    

    View Slide

42. "book": {
    "name": "Steve Jobs",
    "author": "Walter Isaacson",
    "lenders" = [{
    "person_id": 1234,
    "person_name": "Fred",
    "person_lastname": "Brunel"
    }]
    }
    BAD
    Wednesday, 29 February, 12
    

    View Slide

43. "book": {
    "name": "Steve Jobs",
    "author": "Walter Isaacson",
    "lenders" = [{
    "id": 1234,
    "name": "Fred",
    "lastname": "Brunel"
    }]
    }
    GOOD
    Wednesday, 29 February, 12
    

    View Slide

44. ...
    "user_mentions": [{
    "id": 22548447,
    "id_str": "22548447",
    "screen_name": "rno",
    "name": "Arnaud Meunier",
    "indices": [0, 4]
    ]}
    ...
    Wednesday, 29 February, 12
    

    View Slide

45. Pick the right
    granularity.
    Denormalize!
    Wednesday, 29 February, 12
    

    View Slide

46. "result": {
    ...
    "categories" = [{ "id": 2 }],
    "images": [{ "id": 317171 }],
    "tags": [{ "id": 555 }]
    ...
    }
    Wednesday, 29 February, 12
    

    View Slide

47. "result": {
    ...
    "categories": [{
    "id": 2
    "name" = "food"
    }],
    "images" = [{
    "id": 317171
    "url": "http://image.com/a.png"
    }], ...
    }
    Wednesday, 29 February, 12
    

    View Slide

48. Denormalize the most
    common fields.
    Avoid unnecessary
    roundtrips.
    Wednesday, 29 February, 12
    

    View Slide

49. Don’t make the app
    connects to 10 3rd-
    party systems.
    Aggregate on the
    backend.
    Wednesday, 29 February, 12
    

    View Slide

50. The backend has the
    power, bandwidth
    and knowledge.
    Use it!
    Wednesday, 29 February, 12
    

    View Slide

51. Make it fast!
    Some good techniques
    to be aware of.
    Wednesday, 29 February, 12
    

    View Slide

52. JSON is fast to parse,
    but still, compress
    everything.
    Wednesday, 29 February, 12
    

    View Slide

53. Use Cache-Control on
    every response that
    can be cached.
    Wednesday, 29 February, 12
    

    View Slide

54. Partial Responses &
    Partial Updates
    Let the client decides
    what to get/update.
    Wednesday, 29 February, 12
    

    View Slide

55. GET
    http://www.google.com/calendar/
    feeds/zachpm@google.com/private/
    full?fields=entry(title,gd:when)
    Wednesday, 29 February, 12
    

    View Slide

56. PATCH /myfeed/1/1/
    Content-Type: application/xml
    xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google...'
    gd:fields='description'>
    New title
    
    Wednesday, 29 February, 12
    

    View Slide

57. Batch Requests
    Send multiple
    operations, get one
    answer.
    Wednesday, 29 February, 12
    

    View Slide

58. Persistent
    Connections.
    Keep a connection
    nailed up.
    Wednesday, 29 February, 12
    

    View Slide

59. “If you’re serious
    about network, you
    should make your
    own protocol.”
    —Fake Alan Kay.
    Wednesday, 29 February, 12
    

    View Slide

60. The fabric of the
    Internet is TCP/IP, not
    HTTP.
    Wednesday, 29 February, 12
    

    View Slide

61. Make your own
    Binary Protocol.
    Lot faster than text +
    compression. Sorry!
    Wednesday, 29 February, 12
    

    View Slide

62. Message-based API
    Custom TLV
    MessagePack
    ProtocolBuffers
    Wednesday, 29 February, 12
    

    View Slide

63. TAG LENGTH VALUE
    32 bits
    16 bits n bits
    TLV TLV TLV TLV TLV
    TLV TLV TLV TLV TLV
    messages streaming
    a message
    Wednesday, 29 February, 12
    

    View Slide

64. message Person {
    required string name = 1;
    required int32 id = 2;
    optional string email = 3;
    enum PhoneType {
    MOBILE = 0;
    HOME = 1;
    WORK = 2;
    }
    message PhoneNumber {
    required string number = 1;
    optional PhoneType type = 2 [default = HOME];
    }
    repeated PhoneNumber phone = 4;
    }
    Wednesday, 29 February, 12
    

    View Slide

65. Person person;
    person.set_name("John Doe");
    person.set_id(1234);
    person.set_email("jdoe@example.com");
    fstream output("myfile", ios::out | ios::binary);
    person.SerializeToOstream(&output);
    fstream input("myfile", ios::in | ios::binary);
    Person person;
    person.ParseFromIstream(&input);
    cout << "Name: " << person.name() << endl;
    cout << "E-mail: " << person.email() << endl;
    Wednesday, 29 February, 12
    

    View Slide

66. So.
    They are tons of
    efficient solutions
    and techniques.
    Wednesday, 29 February, 12
    

    View Slide

67. Remember.
    Be pragmatic.
    Be consistent
    Be complete.
    Be fast.
    Wednesday, 29 February, 12
    

    View Slide

68. Thank you.
    twitter.com/ runel
    fred@wherecloud.com
    Wednesday, 29 February, 12
    

    View Slide