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