Sildes for Data to Go: Mobile API Design @ SXSW 2014 http://schedule.sxsw.com/2014/events/event_IAP17442

1. Data to Go
Mobile API Design
Matt Smollinger
CTO & Co-Founder, Skaffl
@mattsmollinger
Chuck Greb
Sr. Software Engineer, Mapzen
@ecgreb
#SXSW
#DataToGo

2. About us
Chief Technology Officer of Skaffl.
com, Mobile Dev, and general geek.
Mobile software craftsman, test-
driven evangelist, and clean code
connoisseur.
Matt Smollinger
CTO & Co-Founder, Skaffl
@mattsmollinger
Chuck Greb
Sr. Software Engineer, Mapzen
@ecgreb

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

5. 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

6. Remote Service API
● Web service
● Desktop, laptop, or mobile client
● Communication and protocol
HTTP + JSON = <3

7. Web API Request

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

10. Yo ho ho and a few
billion pageviews of
RUM
Josh Fraser, Torbit, 2012

12. How speed affects bounce rate
(Fraser, 2012, p. 30)

13. How speed affects bounce rate (mobile)
(Fraser, 2012, p. 34)

14. How speed affects user engagement
(Fraser, 2012, p. 35)

15. How speed affects user engagement (mobile)
(Fraser, 2012, p. 37)

16. The Three Little APIs
Once upon a time...

17. Things users care about
● Speed
● Battery life
● Privacy

18. Public vs. Private APIs
Is your API open to 3rd party developers?

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

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

22. Catomatic
Node Instance: http://mostlygeeks.com:5000/
https://github.com/msmollin/sxsw_node
https://github.com/msmollin/catomatic_ios
https://github.com/ecgreb/catomatic

23. Reduce round trips
to the server
Principle #1

24. Resource constrained environment
● CPU
● memory
● bandwidth
● battery

25. 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

26. Users are impatient
● Reduce network overhead
● Brevity trumps discoverability
● RESTful vs. RESTish

27. Mobile Performance
from Radio Up
Ilya Grigorik, Google, 2013

29. The (short) life of a web request
(Grigorik, 2013, p. 20)

30. Watch those energy tails!
(Grigorik, 2013, p. 23)

31. HSPA vs LTE (U.S.)
(Grigorik, 2013, p. 37)

32. HSPA vs LTE (World)
(Grigorik, 2013, p. 37)

33. Show me the cache
● Memory
● Disk
● Invalidation
Chiu-Ki Chan
Caching Strategies for Mobile Apps
Philly ETE 2012
http://chiuki.github.io/mobile-caching-strategies/

34. - Phil Karlton
"There are two hard things in
computer science:
cache invalidation, naming
things, and off-by-1 errors."

35. Reduce round trips
to the server
Example #1 (Login)

36. Verify Password
POST http://mostlygeeks.com:5000/api/verify_password
Input
{ "email": "chuck@example.com", "password": "buddy" }
Output
{ "user_id": 1 }

37. Profile
GET http://mostlygeeks.com:5000/api/users/1
{
"user_id": 1,
"name": "Chuck Greb",
"email": "chuck@example.com"
}

38. Cats
GET 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."
},
...
]

39. Login (input)
POST http://mostlygeeks.com:5000/login
{ "email": "chuck@example.com", "password": "buddy" }

40. Login (output)
{
"user": {
"user_id": 1,
"name": "Chuck Greb",
"email": "chuck@example.com"
},
"cats": [
{
"cat_id": 1,
"name": "Kaze",
"age": 2
},
...
]
}

41. Control verbosity
Principle #2

42. Low hanging fruit
● Remove empty data
● Remove irrelevant data
● GZIP compression

43. Time
Data
is
Money
- Benjamin Franklin

44. Sip, don’t chug.
● Less data is faster
● Less data is less expensive

45. Knobs and dials
● Pagination
● Sort
● Search
● Filter

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

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

48. Custom media type
Accept: application/cat.simple+json
http://developer.github.com/v3/media/

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

50. Collection vs. resource
http://example.com/api/cats
http://example.com/api/cats/1

51. Control verbosity
Example #2 (Master/detail)

52. 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."
},
...
]

53. 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..."
}

54. Restrict access
Principle #3

55. Identify the origin of all requests
● Application version
● User account
● Device type
● Operating system
● Network (IP) address
● etc.

56. Deny unauthorized requests
● Invalid credentials
● Rate limit
● Unsupported operating system
● Obsolete application version
● Blacklisted IP address

57. Protect sensitive data
● Personal data
● Proprietary data
● Critical URL Resources

58. Keep it secret. Keep it safe.

59. 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

60. 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

61. Restrict access
Example #3 (Access token)

62. Login
POST http://mostlygeeks.com:5000/login
Input
{ "email": "chuck@example.com", "password": "buddy" }
Output
{
"access_token": "Y2h1Y2tAZXhhbXBsZS5jb20",
"cats": [ ... ]
}

63. Looking to the
future...

64. The Future...

65. ...is now
● SPDY
● Binary Transfer Formats
○ Protobuf
○ BSON
○ Thrift
● Websockets
● HTTP 2.0

66. How was the session?
FeedbackSXSW App Session Feedback
1. Express yourself
2. Help us get better
3.Earn rewards
{Daily SXSW Posters + Grand Prizes}
In 1 minute

67. done.
Matt Smollinger
CTO & Co-Founder, Skaffl
@mattsmollinger
Chuck Greb
Sr. Software Engineer, Mapzen
@ecgreb
#SXSW
#DataToGo