The document discusses Klout's evolution of their APIs to better support mobile use cases. Originally, Klout's Partner API was not mobile optimized, but they later redesigned it to be mobile-friendly by making it JSON-only, easy to access data in two calls, and optimizing payloads for mobile. They also created a separate Mobile API optimized for mobile apps with view-oriented payloads. However, they realized having separate Partner and Mobile APIs created issues, so they moved to a single API approach using entitlements to segment data for different use cases. The document outlines best practices for designing mobile-friendly APIs such as using entitlements, optimizing payloads, limiting requests, and following classic client-server principles.

1. Mobile First… or maybe second.
APICon 2014
Tyler Singletary, Director of Platform
tyler@klout.com ; @harmophone

2. Thinking about mobile means
thinking about APIs
2
(but I don’t have to tell you that)

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

4. Any product is full of tradeoffs.
• We redesigned APIs for
Klout.com and our 1st-party
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.
4
Partner API
• Crowdsourced
Mobile Apps
•CRM,
Enterprise
• Consumer
Master
API
Klout.com
•Mobile
Klout.com
Mobile API
•Official Klout
App
• Cinch

5. Let’s try Mobile Second (sort of)
5

6. Different use cases… same API
/user.json/1
• Klout.com can make several calls, and has expanded feature set. Fullest
payloads. Complete user profile!
• Partner API needs a very sanitized, limited payload. Just the user’s score.
• Mobile API needs this current user, but also should get all other users
6

7. Entitlements
• Can be implemented by header, query parameter, or other means.
• No need to build second endpoint for each use case
• Requires dedicated engineering rigor to be consistent
7

8. Klout Mobile iOS 1.0
8
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
}

9. Let’s try Mobile First! (and only!)
9

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

11. Let’s get balanced
11

12. Optimizing APIs for both allows UX to
dominate
Web Mobile 2.0 iOS/Android

13. Serve not only yourself, but others…
• We should have branched another
“Mobile Partner API” to ease in partner
development of mobile apps utilizing
our API.
13
Partner API
• CRM,
Enterprise
• Consumer
Master
API
Mobile API
• Official Klout
App
• Cinch
Mobile
Partner API
• Appboy
Klout.com
November 2013 Update:
We still haven’t done this. 
May 2014 Update:
We still haven’t done this. :(

14. I feel like this is all so familiar.
14

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

16. Mobile Clients and Hardware Dictate Challenges
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.
16

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

18. Lessons Learned
18

19. How Do You Protect Against These Challenges?
Remove
extraneous
data
Deliver large
payloads,
fewer requests
Real work
should be done
on the server
Try, try, again.
But not too
much.
Graceful
Degregation
Classic Client Server Principles 19

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

21. 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!”
21

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

23. Best Practices
• Envelopes are an essential way to control and react to change, impress an
update.
• Entitlements allow you to reform and segment your API for use cases
• Default to POST and PUT with arrays, even for single record updates.
• Reference both URLs to resources as well as content_ids
23

24. More Best Practices
• 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
24

25. Error states and hypermedia
• 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 (Hypermedia to the rescue!):
– Bon Longden’s vnd.error : https://github.com/blongden/vnd.error
25

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

27. Mobile First… or maybe second.
APICon 2014
Tyler Singletary, Director of Platform
tyler@klout.com ; @harmophone