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.

1. Mobile API
Design & Techniques.
Fred Brunel
CTO

2. Why?

3. Though for CPU power
Though for bandwidth
Lazy designed.
Too close to database.

4. A mobile device is
Low powered
Low bandwidth
Runs on battery!

5. A the network is the
weak link.

6. Network conditions
change in real-time.

7. We want to keep the
best user experience
at all time.
Nobody wants an
unresponsive app.

8. The features of an
API has a huge
impact on
performances.

9. An API is a contract
that dictates what
can or cannot be
done (directly).

10. When the API is too
lazy, or incomplete;
the burden is put on
the mobile app.

11. Any workaround put
a stress on the
mobile app to use
too much network.

12. API = User Interface.
Should be simple and
get the job done. Fast.

13. Landlord Report.

14. Simple
Standard Complete

15. Simple
Standard Complete
SOAP
XML-RPC
WS-*
Pure REST

16. Simple
Complete

17. Trust the OSI model.
Works everywhere.
And it’s plenty enough.
http://en.wikipedia.org/wiki/OSI_model

18. REST-ish API + JSON
Pure REST is a nice to
have but not a goal.

19. GET/POST + Action +
Params is fine.
PUT/DELETE are nice
to have.

20. Twitter is also REST-ish
POST statuses/create
POST statuses/destroy/:id
POST statuses/update

21. REST put an emphasis
on actions applied to
resources; but the
issue is the
representation.

22. Simplify the life of the
implementor.
Be pragmatic.

23. When designing your
API payloads, pay
attention to
consistency and
completeness.

24. Consistency means
developer know what
to expect.
Principle of least
astonishment.

25. Completeness means
less roundtrips.

26. HTTP latency on 3G
~ 1 second.
Every request count.

27. API is NOT a CRUD
interface to your SQL
database.
It’s a facade.

28. Database
Facade
API
App
Data
Representation
Raw DataDisplay

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

30. So, how do we start
from here?

31. Most of the time, a
mobile API will be use
to get information to
be displayed on a
screen.

32. Reverse Design.
Start from the UI
Not the data

33. 1. Think screens
2.Entities to display
3.Design entity models
4.Design services

35. ID
Title
Town
Country
Rating
Thumbnail URL
Geocode
Website
Email
Description

36. Then, format the
representation to be as
efficient as possible.

37. Each JSON entity should
have the same consistent
representation.
Be coherent!

38. "person": {
"id": 1234,
"name": "Fred",
"lastname": "Brunel",
"company": "WhereCloud"
}

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

40. "book": {
"name": "Steve Jobs",
"author": "Walter Isaacson",
"lenders" = [{
"id": 1234,
"name": "Fred",
"lastname": "Brunel"
}]
}
GOOD

41. ...
"user_mentions": [{
"id": 22548447,
"id_str": "22548447",
"screen_name": "rno",
"name": "Arnaud Meunier",
"indices": [0, 4]
]}
...

42. Pick the right granularity.
Denormalize!

43. "result": {
...
"categories" = [{ "id": 2 }],
"images": [{ "id": 317171 }],
"tags": [{ "id": 555 }]
...
}

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

45. Denormalize the most
common fields.
Avoid unnecessary
roundtrips.

46. Don’t make the app
connects to 10 3rd-
party systems.
Aggregate on the
backend.

47. The backend has the
power, bandwidth
and knowledge.
Use it!

48. Make it fast!
Some good techniques
to be aware of.

49. JSON is fast to parse,
but still, compress
everything.

50. Use Cache-Control on
every response that
can be cached.

51. Partial Responses &
Partial Updates
Let the client decides
what to get/update.

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

53. PATCH /myfeed/1/1/
Content-Type: application/xml
<entry
xmlns='http://www.w3.org/2005/Atom'
xmlns:gd='http://schemas.google...'
gd:fields='description'>
<title>New title</title>
</entry>

54. Batch Requests
Send multiple
operations, get one
answer.

55. Persistent
Connections.
Keep a connection
nailed up.

56. “If you’re serious
about network, you
should make your
own protocol.”
—Fake Alan Kay.

57. The fabric of the
Internet is TCP/IP, not
HTTP.

58. Make your own
Binary Protocol.
Lot faster than text +
compression. Sorry!

59. Message-based API
Custom TLV
MessagePack
ProtocolBuffers

60. TAG LENGTH VALUE
32 bits16 bits n bits
TLV TLV TLV TLV TLV
TLV TLV TLV TLV TLV
messages streaming
a message

61. 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;
}

62. 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;

63. So.
They are tons of
efficient solutions
and techniques.

64. Remember.
Be pragmatic.
Be consistent
Be complete.
Be fast.

65. Thank you.
twitter.com/fbrunel
fred@wherecloud.com