Post on 16-May-2015
Mobile API Design
Chuck GrebMobile Platform ArchitectAWeber Communications@ecgreb
Data To Go
I'm an Android guy...
A Brief Survey
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
● Remote (web-based) service● Desktop, laptop, or mobile client● Communication protocol and data model
Remote Service API
Web API Request
Mobile API requests are generally slower and more prone to timeouts and other failures!
Mobile API Request
● Who is your audience?● Is your API open to 3rd party developers?
Public vs. Private APIs
1. Reduce round trips to the server2. Control verbosity3. Restrict access
3 Principles of Mobile API Design
Principle #1Reduce round trips to the server
Resources are limited.
Principle #1Reduce round trips to the server
Mobile resource constraints● battery● bandwidth● memory● cpu
Principle #1Reduce round trips to the server
Eliminate network overhead.
Principle #1Reduce round trips to the server
Brevity trumps discoverability.
Principle #1Reduce round trips to the server
Users are impatient.
Principle #1Reduce round trips to the server
EndpointPOST https://example.com/api/verify_password
Input{"username":"ecgreb", "password":"buddy"}
Output{"success":true}
Example #1Login
EndpointGET https://example.com/api/users/ecgreb
Output{ "user_id":12345 "name":"Chuck Greb" "avatar":"http://example.com/images/image001.jpg" ...}
Example #1Login
EndpointGET https://example.com/api/users/12345/analytics
Output{ "subscribers":47 "unsubscribes":18 "open_rate":0.74468085 "click_rate":0.30882353 ...}
Example #1Login
EndpointPOST https://example.com/api/login
Input{"username":"ecgreb", "password":"buddy"}
Example #1Login
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 #1Login
Principle #2Control verbosity
Purge empty and irrelevant data.
Principle #2Control verbosity
Pay by the byte.
Principle #2Control verbosity
Use compression.
Principle #2Control verbosity
Specify verbosity level per request.
Principle #2Control verbosity
Object Expansion● Abstract verbosity level● Custom media type● Specify response fields in the request
Principle #2Control verbosity
Abstract verbosity level (1-5)
https://example.com/api/users/12345?verbosity=3
Principle #2Control verbosity
Custom media type
Accept: application/json+user.simple
Principle #2Control verbosity
Specify response fields
https://example.com/api/users/12345?fields=[id,name,avatar]
Principle #2Control verbosity
EndpointGET https://example.com/api/users/12345/messages
Output{"messages": [ { "id":1, "title":"Welcome!", "open_rate":0.74468085, "click_rate":0.30882353 }, ...]}
Example #2Messages
EndpointGET 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 #2Messages
Principle #3Restrict access
Identify the source of all incoming requests.
Principle #3Restrict access
Deny unauthorized requests.
Principle #3Restrict access
Protect sensitive data.
Principle #3Restrict access
Use a mobile-friendly security model.
Principle #3Restrict access
EndpointPOST 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 #3Login
1. Reduce round trips to the server2. Control verbosity3. Restrict access
3 Principles of Mobile API Design
Thank YouQuestions?
Chuck GrebMobile Platform ArchitectAWeber Communications@ecgreb