Data to GoMobile API DesignMatt SmollingerCTO & Co-Founder, Skaffl@mattsmollinger

Chuck GrebSr. Software Engineer, Mapzen@ecgreb

#SXSW #DataToGo

About us

Chief Technology Officer of Skaffl.com, Mobile Dev, and general geek.

Mobile software craftsman, test-driven evangelist, and clean code connoisseur.

Matt SmollingerCTO & Co-Founder, Skaffl@mattsmollinger

Chuck GrebSr. Software Engineer, Mapzen@ecgreb

Agenda

● Overview● 3 Principles of (good) mobile API design● Looking to the future

What is an API?

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.

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

Remote Service API

● Web service● Desktop, laptop, or mobile client● Communication and protocol

HTTP + JSON = <3

Web API Request

Mobile API Request

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

Yo ho ho and a few billion pageviews of RUMJosh Fraser, Torbit, 2012

How speed affects bounce rate

(Fraser, 2012, p. 30)

How speed affects bounce rate (mobile)

(Fraser, 2012, p. 34)

How speed affects user engagement

(Fraser, 2012, p. 35)

How speed affects user engagement (mobile)

(Fraser, 2012, p. 37)

The Three Little APIs

Once upon a time...

Things users care about

● Speed● Battery life● Privacy

Public vs. Private APIs

Is your API open to 3rd party developers?

3 Principles of Mobile API Design

1. Reduce round trips to the server2. Control verbosity3. Restrict access

Catomatic

● Node.js server (Express)● iOS client● Android client

CatomaticNode Instance: http://mostlygeeks.com:5000/

https://github.com/msmollin/sxsw_node

https://github.com/msmollin/catomatic_ios

https://github.com/ecgreb/catomatic

Reduce round trips to the serverPrinciple #1

Resource constrained environment

● CPU● memory● bandwidth● battery

Hardware comparison

Moto X● Snapdragon S4 Pro● Dual-core● 1.7 GHz● 2GB RAM

Apple iMac● Intel Core i7● Quad-core + HT● 3.4 GHz● 8GB RAM (standard)● Up to 32GB

Users are impatient

● Reduce network overhead● Brevity trumps discoverability● RESTful vs. RESTish

Mobile Performance from Radio UpIlya Grigorik, Google, 2013

The (short) life of a web request

(Grigorik, 2013, p. 20)

Watch those energy tails!

(Grigorik, 2013, p. 23)

HSPA vs LTE (U.S.)

(Grigorik, 2013, p. 37)

HSPA vs LTE (World)

(Grigorik, 2013, p. 37)

Show me the cache

● Memory● Disk● Invalidation

Chiu-Ki ChanCaching Strategies for Mobile AppsPhilly ETE 2012http://chiuki.github.io/mobile-caching-strategies/

- Phil Karlton

"There are two hard things in computer science:

cache invalidation, naming things, and off-by-1 errors."

Reduce round trips to the serverExample #1 (Login)

Verify PasswordPOST http://mostlygeeks.com:5000/api/verify_password

Input{ "email": "chuck@example.com", "password": "buddy" }

Output{ "user_id": 1 }

ProfileGET http://mostlygeeks.com:5000/api/users/1

{

"user_id": 1,

"name": "Chuck Greb",

"email": "chuck@example.com"

}

CatsGET http://mostlygeeks.com:5000/cats

[

{

"cat_id": 1,

"name": "Kaze",

"age": 2,

"small_photo_url": "http://example.com/images/kaze_small.jpg",

"short_description": "Kaze is an energetic and playful cat."

},

...

]

Login (input)POST http://mostlygeeks.com:5000/login

{ "email": "chuck@example.com", "password": "buddy" }

Login (output){

"user": {

"user_id": 1,

"name": "Chuck Greb",

"email": "chuck@example.com"

},

"cats": [

{

"cat_id": 1,

"name": "Kaze",

"age": 2

},

...

]

}

Control verbosityPrinciple #2

Low hanging fruit

● Remove empty data● Remove irrelevant data● GZIP compression

Time

Data

is

Money- Benjamin Franklin

Sip, don’t chug.

● Less data is faster● Less data is less expensive

Knobs and dials

● Pagination● Sort● Search● Filter

Object Expansion

Specify verbosity level on per request basis● Abstract verbosity level● Custom media type● Specify response fields in the request● Collection vs. resource

Abstract verbosity level

http://example.com/api/cats?verbosity=3

Custom media type

Accept: application/cat.simple+json

http://developer.github.com/v3/media/

Specify response fields

http://example.com/api/cats?fields=[cat_id,name,age]

Collection vs. resource

http://example.com/api/cats

http://example.com/api/cats/1

Control verbosityExample #2 (Master/detail)

Cats (collection)GET http://mostlygeeks.com:5000/cats

Output[

{

"cat_id": 1,

"name": "Kaze",

"age": 2,

"photo_url": "http://example.com/images/kaze.jpg",

"short_description": "Kaze is an energetic and playful cat."

},

...

]

Cat (resource)GET http://mostlygeeks.com:5000/cats/1

Output{

"cat_id": 1,

"name": "Kaze",

"age": 2,

"small_photo_url": "http://example.com/images/kaze_small.jpg",

"short_description": "Kaze is an energetic and playful cat.",

"large_photo_url": "http://example.com/images/kaze_large.jpg",

"long_description": "Kaze is an energetic and playful cat who likes to..."

}

Restrict accessPrinciple #3

Identify the origin of all requests

● Application version● User account● Device type● Operating system● Network (IP) address● etc.

Deny unauthorized requests

● Invalid credentials● Rate limit● Unsupported operating system● Obsolete application version● Blacklisted IP address

Protect sensitive data

● Personal data● Proprietary data● Critical URL Resources

Keep it secret. Keep it safe.

Mobile-friendly security

Do● HTTPS/SSL● Access token

header● 2-step verification

Don’t● Session● Cookies● CSRF tokens● OAuth*● HMAC**Unless your API is public

Wait... I thought OAuth was good?

● Which implementation?● Designed for 3-legged communication over

un-encrypted connections.● Apps can be decompiled to determine

hashing algorithm if done client-side.● Introduces significant overhead.● OAuth2 = Security Sadness

Restrict accessExample #3 (Access token)

LoginPOST http://mostlygeeks.com:5000/login

Input{ "email": "chuck@example.com", "password": "buddy" }

Output{

"access_token": "Y2h1Y2tAZXhhbXBsZS5jb20",

"cats": [ ... ]

}

Looking to the future...

The Future...

...is now

● SPDY● Binary Transfer Formats

○ Protobuf○ BSON○ Thrift

● Websockets● HTTP 2.0

How was the session?

FeedbackSXSW App Session Feedback

1. Express yourself2. Help us get better

3.Earn rewards{Daily SXSW Posters + Grand Prizes}

In 1 minute

done.Matt SmollingerCTO & Co-Founder, Skaffl@mattsmollinger

Chuck GrebSr. Software Engineer, Mapzen@ecgreb

#SXSW #DataToGo