Klout redesigned their APIs in 2012 to better support mobile applications. They created a Master API that feeds both their Mobile API and Partner API. The Mobile API provides optimized payloads for mobile with all needed data in one request to reduce requests. They realized they should have created a separate Mobile Partner API to more easily support third-party mobile app development. The document outlines best practices for mobile APIs, including minimizing data payloads and requests, handling errors, and designing for failure and changes.

1. Mobile APIs In Practice
November 2013
Tyler Singletary, Director of Platform
tyler@klout.com ; @harmophone

2. When Klout Started Thinking Mobile
Klout’s Partner API in
2010-2011:
Klout’s API Strategy in
2012+:
• Not Mobile Optimized
• Not Used on Klout.com
• Not Extensible.
• XML and JSON response
• No Mobile Web Experience
• Easy Data in 1 Call
• Acquired Blockboard
• Redesigned Central API
• Entitlement System for
Klout.com, Mobile, Partners
• Mobile Web
• JSON Only
• Easy Data in 2 Calls for
Partners
2

3. Tradeoffs at Klout
•
•
•
We redesigned APIs for
Klout.com and our 1stparty mobile App first.
The Partner API drove
some of the
requirements, but always
would be based on the
Master API (with hidden
data)
The Mobile API payloads
are optimized for mobile
and its specific functions.
Partner API
• Crowdsourced
Mobile Apps
• CRM, Enterprise
• Consumer
Master
API
Mobile API
• Official Klout App
• Cinch
Klout.com
• Mobile Klout.com
3

4. Klout Mobile
All data in one
payload.
{
response: {
user: {
kloutId: "478569",
nick: "harmophone",
name: {
firstName: "devty",
lastName: "T"
},
image: {
network: {
identifier: "tw",
number: 1
},
urlTiny:
"http://a0.twimg.com/profile_images/23083
33289/7s7abq8j02kuxf84g7ig_normal.jpeg",
urlSmall:
"http://a0.twimg.com/profile_images/23083
33289/7s7abq8j02kuxf84g7ig_reasonably_s
mall.jpeg",
urlMedium:
"http://a0.twimg.com/profile_images/23083
33289/7s7abq8j02kuxf84g7ig_reasonably_s
mall.jpeg",
urlLarge:
"http://a0.twimg.com/profile_images/23083
33289/7s7abq8j02kuxf84g7ig.jpeg",
networkImage:
"http://a0.twimg.com/profile_images/23083
33289/7s7abq8j02kuxf84g7ig_normal.jpeg"
},
bio: "Adagio assai. Klout Devangelist.",
bioSource: "tw",
score: {
score: 47.620975824983596,
trueReach: 537
},
scoreDeltas: {
dayChange: -0.16153993062354743,
weekChange: -0.5384216786696854,
monthChange: -1.8510836286192287
},
connectedNetworks: [
{
id: “",
network: "tw"
}
],
hasMobile: true
},
topics: […],
sourceOfInfluence: {
myInfluencers: […],
myInfluencees: […],
},
preferences: {},
scoreHistory: {},
stats: { },
networkContributions: { }
},
responseTime: 44
}
4

5. Klout’s Cinch APIs
View-oriented
payloads
5

6. What We Should Have Done
•
•
We should have branched another
“Mobile Partner API” to ease in partner
development of mobile apps utilizing
our API.
November 2013 Update:
– We still haven’t done this. :(
Partner API
• CRM, Enterprise
• Consumer
Klout.com
Master
API
Mobile API
• Official Klout App
• Cinch
Mobile Partner
API
• Appboy
6

7. Division of Labor
Server
Client/App
• Talks to all external
APIs
• Proxy and repackage
content exactly how
the app needs it
• Truth
• Talks only to
Server, except for
auth (but even
then…)
• Temporary storage for
UX and rendering
• Maybe Truth
7

8. Problems With Any API in Mobile
Data transfer rate is typically
slower
Delivering data to a device
costs the consumer money
Any one or more requests
can fail. And will.
Apps collecting from multiple
sources will be slow.
Latency.
Device diversity, processing
power, multitasking, storage
Mobile development has a
slower cycle due to App
Publishing
APIs Change. Apps change.
Not always in sync.
8

9. The Main Conflict
Larger
Data
Payload
• Quick bursts of dense
information
• Just the facts
• But extensible
Less
Requests
9

10. How Do You Protect Against These?
Remove
extraneous
data
Deliver large
payloads, fewe
r requests
Try, try, again.
But not too
much.
Real work
should be done
on the server
Graceful
Degregation
10

11. Failure is Routine. Plan for it.
Requests
User
Detail
Twitter Stream
Server
User
Detail
Twitter Stream
App – 3G
User
Deta--------------tream
It’s a race against time!
11

12. The Problem With SOAP
•
•
•
•
Tons of Extraneous Data.
Big payload.
Processing response holds UI latency.
Out of fashion for big data, social, web at
large.
The Good:
• Type safety!
• Fast Infoset standard. “The GZIP for
XML!”
12

13. The Problem With REST and JSON
•
•
•
•
•
Resource collections and objects aren’t always best
Non-optimized APIs require tons of individual requests
Various interpretations of what REST is and isn’t
Error Handling gets weird with arrays/collections and mobile nuance
While not strictly part of REST, typically JSON.
13

14. Best Practices
• Envelopes are an essential way to control and react to change, impress an
update.
• Default to POST and PUT with arrays, even for single record updates.
• Reference both URLs to resources as well as content_ids
• GZIP or compress responses whenever possible
• OAuth/xAuth for authentication. Don’t roll your own.
• Return collections with reasonable limits. Employ params or headers.
• Version on a per-endpoint basis. Adopt easy, programmatic versioning.
• Clients should identify themselves thoroughly. Version, platform, etc. It’s
shipped software. The API needs to know who it’s talking to.
• Be able to specify a “critical read” -> indicating acceptance of longer latency
or bypassing cache responses
14

15. Just one more thing… (about errors)
• Use HTTP status when appropriate
• Server-side errors need clarity and extensibility, like exceptions.
– Utilize custom schemes (-10, -11, etc.)
– Use 500-504, but provide codified directive error messages inside.
• Require server to return a handshake at the end of Writes: in addition to
positive status codes, return a positive ACK that a server handled the write.
• Potential Standards: vnd.error : https://github.com/blongden/vnd.error
15

16. Summary
Master API -> Partner API
Mobile API, Mobile Partner API
Design for Mobile APIs:
• both internal and external
Mobile payloads:
• data rich, extensible, lean on the
DDL and extras. Low # of calls.
{
Mobile Envelope:
• should become a standard way of
change management
"response":{},
"responseTime":26,
"interstitial":{
"url": "http://m.klout.com/upgrade",
}
}
16

17. Mobile APIs In Practice
November 2013
Tyler Singletary, Director of Platform
tyler@klout.com ; @harmophone