17
Tyler Singletary, Director of Platform [email protected] ; @harmophone Mobile APIs In Practice November 2013

Mobile APIs in Practice

Embed Size (px)

Citation preview

Tyler Singletary, Director of [email protected] ; @harmophone

Mobile APIs In PracticeNovember 2013

2

When Klout Started Thinking Mobile

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

3

Tradeoffs at Klout

• 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

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/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}

5

Klout’s Cinch APIs

View-oriented payloads

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. :( Master

API

Partner API• CRM,

Enterprise• Consumer

Mobile API• Official Klout

App• Cinch

Mobile Partner API• Appboy

Klout.com

7

Division of Labor

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

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.

9

The Main Conflict

Larger Data

Payload

Less Requests

• Quick bursts of dense information

• Just the facts• But extensible

10

How Do You Protect Against These?

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

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!

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

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.

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

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

16

Summary

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", }}

Master API -> Partner APIMobile API, Mobile Partner API

Tyler Singletary, Director of [email protected] ; @harmophone

Mobile APIs In PracticeNovember 2013