Mobile First (or maybe second) API Development
Upcoming SlideShare
Loading in...5
×
 

Mobile First (or maybe second) API Development

on

  • 138 views

 

Statistics

Views

Total Views
138
Views on SlideShare
126
Embed Views
12

Actions

Likes
0
Downloads
2
Comments
0

1 Embed 12

https://twitter.com 12

Accessibility

Categories

Upload Details

Uploaded via as Microsoft PowerPoint

Usage Rights

© All Rights Reserved

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
    Processing…
Post Comment
Edit your comment
  • A Note On My Perspective: <br /> Klout builds consumer experiences. We measure influence on social networks. <br /> I manage all partner relations in regards to data in and out, as well as managed the development of our new API and how it was divided for Mobile. <br /> My experience is primarily in this context.
  • We broke one cardinal rule for easily getting to data on Mobile: we made it require two calls. <br /> Our data model shifted from being keyed off of Twitter to being keyed off of internal Ids. <br /> Internal IDs are translated from social services, like Twitter, Google+, etc. <br /> Data is then accessed via those IDs <br /> People are influential about Topics <br /> Topics are named entities, but also have unique identifiers referenced by RESTful routes and IDs. <br />
  • Here’s where I get super opinionated. <br /> This applies to web as well. <br />
  • In our mobile API protocol: interstitial can return a URL to a webview in case of a change to invaldate or redirect a client. <br /> Deal with versioning clients to gracefully escape users to the newest versions
  • Cancel/Retry modals on Failure – usual. <br /> Write autoretry or store the POST for future use (always let the user know) <br /> Timers on state <br />
  • Be able to specify a “critical read” -> indicating acceptance of longer latency or bypassing cache responses <br /> <br />
  • If something like a “notif” object exists, include shortened versions of Actor and Subject objects in the payload, rather than reference them for future lookup. <br />
  • 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. <br /> <br /> <br /> Envelope the error messages – present user-readable error messages in the error response (in addition to developer responses) <br /> <br /> API endpoint that is a config file : apps local config file to manange features : <br /> <br /> <br />
  • A Note On My Perspective: <br /> Klout builds consumer experiences. We measure influence on social networks. <br /> I manage all partner relations in regards to data in and out, as well as managed the development of our new API and how it was divided for Mobile. <br /> My experience is primarily in this context.

Mobile First (or maybe second) API Development Mobile First (or maybe second) API Development Presentation Transcript

  • Tyler Singletary, Director of Platform tyler@klout.com ; @harmophone Mobile First… or maybe second. APICon 2014
  • Thinking about mobile means thinking about APIs 2 (but I don’t have to tell you that)
  • 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
  • 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 Master API Partner API • Crowdsourced Mobile Apps • CRM, Enterprise • Consumer Klout.com • Mobile Klout.com Mobile API • Official Klout App • Cinch
  • Let’s try Mobile Second (sort of) 5
  • 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
  • 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
  • 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 }
  • Let’s try Mobile First! (and only!) 9
  • Klout’s Cinch APIs 10 View-oriented payloads
  • Let’s get balanced 11
  • Optimizing APIs for both allows UX to dominate Web Mobile 2.0 iOS/Android
  • 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 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. :(
  • I feel like this is all so familiar. 14
  • 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
  • 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
  • The Main Conflict 17 Larger Data Payload Less Requests • Quick bursts of dense information • Just the facts • But extensible
  • Lessons Learned 18
  • 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 19 Classic Client Server Principles
  • 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!
  • 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
  • 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
  • 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
  • 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
  • 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
  • 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
  • Tyler Singletary, Director of Platform tyler@klout.com ; @harmophone Mobile First… or maybe second. APICon 2014