This document outlines three principles for designing mobile APIs: 1. Reduce round trips to the server by bundling data into single requests to minimize network overhead which conserves mobile resources. 2. Control verbosity by purging unnecessary data, using compression, and allowing clients to specify desired response fields to reduce payload size. 3. Restrict access by identifying request sources, denying unauthorized requests, and protecting sensitive data with a mobile-friendly security model. Examples are provided to illustrate each principle in action.

1. Mobile API Design
Chuck Greb
Mobile Platform Architect
AWeber Communications
@ecgreb
Data To Go

2. I'm an Android guy...

3. A Brief Survey

4. An application programming interface (API)
is a specification of how software
components should interact with each other.
In most cases an API is a library that
includes specification for routines, data
structures, object classes, and variables.
What is an API?
http://en.wikipedia.org/wiki/Application_programming_interface

5. ● Remote (web-based) service
● Desktop, laptop, or mobile client
● Communication protocol and data model
Remote Service API

6. Web API Request

7. Mobile API requests are
generally slower and more
prone to timeouts and other
failures!
Mobile API Request

8. ● Who is your audience?
● Is your API open to 3rd party developers?
Public vs. Private APIs

9. 1. Reduce round trips to the server
2. Control verbosity
3. Restrict access
3 Principles of Mobile API Design

10. Principle #1
Reduce round trips to the server

11. Resources are limited.
Principle #1
Reduce round trips to the server

12. Mobile resource constraints
● battery
● bandwidth
● memory
● cpu
Principle #1
Reduce round trips to the server

13. Eliminate network overhead.
Principle #1
Reduce round trips to the server

14. Brevity trumps discoverability.
Principle #1
Reduce round trips to the server

15. Users are impatient.
Principle #1
Reduce round trips to the server

16. Endpoint
POST https://example.com/api/verify_password
Input
{"username":"ecgreb", "password":"buddy"}
Output
{"success":true}
Example #1
Login

17. Endpoint
GET https://example.com/api/users/ecgreb
Output
{
"user_id":12345
"name":"Chuck Greb"
"avatar":"http://example.com/images/image001.jpg"
...
}
Example #1
Login

18. Endpoint
GET https://example.com/api/users/12345/analytics
Output
{
"subscribers":47
"unsubscribes":18
"open_rate":0.74468085
"click_rate":0.30882353
...
}
Example #1
Login

19. Endpoint
POST https://example.com/api/login
Input
{"username":"ecgreb", "password":"buddy"}
Example #1
Login

20. Output
{
"user": {
"id":12345,
"name":"Chuck Greb",
"avatar":"http://example.com/images/image001.jpg"
},
"analytics": {
"subscribers":47,
"unsubscribes":18,
"open_rate":0.74468085,
"click_rate":0.30882353
},
...
}
Example #1
Login

21. Principle #2
Control verbosity

22. Purge empty and irrelevant data.
Principle #2
Control verbosity

23. Pay by the byte.
Principle #2
Control verbosity

24. Use compression.
Principle #2
Control verbosity

25. Specify verbosity level per request.
Principle #2
Control verbosity

26. Object Expansion
● Abstract verbosity level
● Custom media type
● Specify response fields in the request
Principle #2
Control verbosity

27. Abstract verbosity level (1-5)
https://example.com/api/users/12345?verbosity=3
Principle #2
Control verbosity

28. Custom media type
Accept: application/json+user.simple
Principle #2
Control verbosity

29. Specify response fields
https://example.com/api/users/12345?fields=
[id,name,avatar]
Principle #2
Control verbosity

30. Endpoint
GET https://example.com/api/users/12345/messages
Output
{"messages": [
{
"id":1,
"title":"Welcome!",
"open_rate":0.74468085,
"click_rate":0.30882353
},
...
]}
Example #2
Messages

31. Endpoint
GET https://example.com/api/users/12345/messages/1
Output
{
"id":1,
"title":"Welcome!",
"open_rate":0.74468085,
"click_rate":0.30882353,
"recipients": [
{"email":"cliff.lee@gmail.com", "name":"Cliff...},
{"email":"dom.brown@gmail.com", "name":Dominic...},
...
]
}
Example #2
Messages

32. Principle #3
Restrict access

33. Identify the source of all incoming requests.
Principle #3
Restrict access

34. Deny unauthorized requests.
Principle #3
Restrict access

35. Protect sensitive data.
Principle #3
Restrict access

36. Use a mobile-friendly security model.
Principle #3
Restrict access

37. Endpoint
POST https://example.com/api/login
Input
{"username":"ecgreb", "password":"buddy"}
Output
{"user": {
"id":12345,
"name":"Chuck Greb",
"avatar":"http://example.com/images/image001.jpg",
"access_token":Y2h1Y2tAZXhhbXBsZS5jb20
},
...
}
Example #3
Login

38. 1. Reduce round trips to the server
2. Control verbosity
3. Restrict access
3 Principles of Mobile API Design

39. Thank You
Questions?
Chuck Greb
Mobile Platform Architect
AWeber Communications
@ecgreb