Tyler Singletary, Director of Platformtyler@klout.com ; @harmophone

Mobile First… or maybe second.APICon 2014

2

Thinking about mobile means thinking about APIs

(but I don’t have to tell you that)

3

How Klout Evolved Its APIs

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.

Master API

Partner API• Crowdsourced

Mobile Apps• CRM, Enterprise• Consumer

Klout.com• Mobile Klout.com

Mobile API• Official Klout App• Cinch

5

Let’s try Mobile Second (sort of)

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

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

8

Klout Mobile iOS 1.0

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/2308333289/7s7abq8j02kuxf84g7ig_normal.jpeg",urlSmall: "http://a0.twimg.com/profile_images/2308333289/7s7abq8j02kuxf84g7ig_reasonably_small.jpeg",urlMedium: "http://a0.twimg.com/profile_images/2308333289/7s7abq8j02kuxf84g7ig_reasonably_small.jpeg",urlLarge: "http://a0.twimg.com/profile_images/2308333289/7s7abq8j02kuxf84g7ig.jpeg",networkImage: "http://a0.twimg.com/profile_images/2308333289/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!)

Klout’s Cinch APIs

View-oriented payloads

11

Let’s get balanced

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.

Master API

Partner API• CRM,

Enterprise• Consumer

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.

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

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.

17

The Main Conflict

Larger Data

Payload

Less Requests

• Quick bursts of dense information

• Just the facts• But extensible

18

Lessons Learned

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

20

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!

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

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.

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

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

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

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

{ "response":{}, "responseTime":26, "interstitial":{ "url": "http://m.klout.com/upgrade", }}

Master API -> Partner APIMobile API, Mobile Partner API

Tyler Singletary, Director of Platformtyler@klout.com ; @harmophone

Mobile First… or maybe second.APICon 2014