Mobile API Design Techniques

Mobile API
Design & Techniques.
Fred Brunel
CTO

Wednesday, 29 February, 12

Why?


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


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


A the network is the
weak link.


Network conditions
change in real-time.


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

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


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


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


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


API = User Interface.

Should be simple and
get the job done. Fast.


Landlord Report.


Simple

Standard Complete

Simple

SOAP
WS-*
Standard Complete
XML-RPC Pure REST

Simple

Complete

Trust the OSI model.
Works everywhere.
And it’s plenty enough.

http://en.wikipedia.org/wiki/OSI_model


REST-ish API + JSON

Pure REST is a nice to
have but not a goal.


GET/POST + Action +
Params is ﬁne.

PUT/DELETE are nice
to have.

Twitter is also REST-ish

POST statuses/create
POST statuses/destroy/:id
POST statuses/update


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

Simplify the life of the
implementor.
Be pragmatic.


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

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

Completeness means
less roundtrips.


HTTP latency on 3G

~ 1 second.

Every request count.

API is NOT a CRUD
interface to your SQL
database.

It’s a facade.

Facade
App Database
API

Data
Display Raw Data
Representation


The facade answer to
high-level questions.

Think services, not
objects and methods.

So, how do we start
from here?


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

Reverse Design.

Start from the UI
Not the data


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


ID
Title
Town
Country
Rating
Thumbnail URL
Geocode
Website
Email
Description


Then, format the
representation to be as
eﬃcient as possible.


Each JSON entity
should have the same
consistent
representation.


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


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

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

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


Pick the right
granularity.

Denormalize!


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


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


Denormalize the most
common ﬁelds.
Avoid unnecessary
roundtrips.


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

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


Make it fast!

Some good techniques
to be aware of.


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


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


Partial Responses &
Partial Updates

Let the client decides
what to get/update.

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


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>


Batch Requests

Send multiple
operations, get one
answer.

Persistent
Connections.

Keep a connection
nailed up.

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


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


Make your own
Binary Protocol.

Lot faster than text +
compression. Sorry!

Message-based API

Custom TLV
MessagePack
ProtocolBuﬀers

a message

TAG LENGTH VALUE
16 bits 32 bits n bits

TLV TLV TLV TLV TLV

TLV TLV TLV TLV TLV

messages streaming


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


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;


So.

They are tons of
eﬃcient solutions
and techniques.

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

Thank you.

twitter.com/fbrunel
fred@wherecloud.com


Mobile API Design Techniques

Related slideshows

More Related Content

Viewers also liked

Viewers also liked (8)

Similar to Mobile API Design Techniques

Similar to Mobile API Design Techniques (16)

More from Trieu Nguyen

More from Trieu Nguyen (20)

Recently uploaded

Recently uploaded (20)

Mobile API Design Techniques