Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Designing your API Server

August 18, 2012

Designing your API Server


August 18, 2012

Other Decks in Technology


  1. About me • Author of the iOS 5 programming: Pushing

    the limits book - Reached the top 100 books in Amazon’s Computer and Technology books list • Trainer - Conducts training on iOS programming at iOSTraining.sg. • Developer • MKNetworkKit (1100+ watchers) • MKStoreKit (700+ watchers) • Several other “minor” projects with 200+ watchers • Clients include startups in Singapore like Squiryl, Found and MNC’s including Microsoft Redmond, Oracle and such. ROB NAPIER MUGUNTH KUMAR Advanced Application Development for Apple iPhone®, iPad® and iPod® Touch PUSHING THE LIMITS iOS 5 PROGRAMMING
  2. VERBS - In REST Parlance • Any API that alters

    or changes the content of the database should use the POST verb • Any API that adds new entries to the database should use the POST or PUT (preferably a PUT) verb • Any API that deletes entries should use the “DELETE” verb • Everything else should use the “GET” verb
  3. VERBS - In developer parlance • If your query is

    “INSERT into TABLE VALUES…” • Your verb should be PUT • If your query is “UPDATE table set…” • Your verb should be a POST • If your query is “DELETE from table WHERE…” • Your verb should be DELETE • If your query is “SELECT * from WHERE…” • Your verb should be GET
  4. What happens instead? • Isn’t that common sense? • Apparently,

    most .NET developers write API servers the old way. • SOAP way • RPC way • One endpoint and every operation is sent as a “POST” parameter • POST api.mycompany.com/api.svc op=“get_profile”
  5. Importance of using the right VERB • “POST” / “PUT”

    methods are non-idempotent and should not be cached. That means, any intermediate proxy server (could be your ISP) will not cache your responses. • In most API servers, >80% of API calls will read data off your database that can be cached. • Just by making a wrong verb choice, you inadvertently add scaling complexity • By using “GET” verb, you can easily introduce a caching proxy and also piggy back on ISP’s proxy servers.
  6. Pure RESTful Server? • Pure RESTful server following a HATEOAS

    has just one endpoint, serves hypermedia resources and expects clients to be RESTful. • JSON is not a hypermedia resource • Adds client complexity - You ought to complete your iOS app in 3 months lest you die • Was nice to have in “olden” days where browsers were “RESTful” clients • Today, developers race to make a “curated” app with a customized experience than a generic, generated user interface.
  7. Documentation • Write and document your top level models •

    Top level models != DAO • Every top level model might have one or more associated DAO • “Tweet” is a top level model and so is “User” or “Profile”
  8. Documentation • Document your API’s parameters and mark optional and

    mandatory parameters. • List out public API, protected API and hybrid APIs • Document your API responses using top-level models • APIs should not have undocumented behavior. • Any non essential parameters like x-client-version or Authorization in HTTP header should be passed in header
  9. Documentation • Example: api.foursquare.com • /venue • accepts a venue

    id • returns a detailed venue object • App.NET (That “upcoming” $50 social network) • Twitter - Extensive and difficult to understand though
  10. DAO vs Top Level Models • A tweet model contains

    the following • The tweet text • The geo location of the tweet • The user who tweeted it • Number of retweets and favorites • The top 10 users who retweeted and favorited the tweet
  11. DAO vs Top Level Models • In a traditional relational

    database, • Tweets would be stored in a “tweets” table • Retweets would be stored in a “retweets” table which might include the time of retweet as well. • So are favorites • The user profile information would be stored in a “users” table
  12. De-Normalization • Your API server should de-normalize information stored in

    different tables into one top level model in your application. • You normalize data as a part of your database design and implementation • You should de-normalize them as a part of your API design and implementation
  13. Ill Effects • If you don’t de-normalize your responses, the

    client device has to make multiple calls • A twitter client will probably make four calls per tweet to show information on a tweet details page • If your Keep-Alive is set to a low number, (default in Apache 2.2) every API call will require a new connection.
  14. Ill Effects • Your sys-admin, as a stop-gap measure, reduces

    the Keep- Alive time. This might work well and improve the server’s ability to handle more requests in parallel • But think again, your server is handling more requests than actually necessary if it were de-normalized • An API that is NOT de-normalized will kill your startup in no time, much like de-normalized database • Cellular networks in 2012 are not as capable as broadband • 6 concurrent connections on broadband vs 2 in 3G
  15. Versioning • Versioning wasn’t a major issue with web based

    applications • Serious issue with disconnected native clients • Version 1 => Profile = { “name”:”Mugunth Kumar”} • Version 2 => Profile = { “first_name”:”Mugunth”, “last_name”:”Kumar”} • Send both in Version 2 => Profile = { “first_name”:”Mugunth”, “last_name”:”Kumar”, “name”:”Mugunth Kumar”} ?
  16. Versioning - Right way • When you deploy API 2.0,

    your server should still be capable of serving 1.x clients because, unlike a traditional web app, you cannot deploy a native client to all your customers at the same time. • Version your models. Maintain multiple versions of top level models mapping to the same DAO • Respect the “Accept” HTTP Header • URL versioning is clumsy
  17. • Accept: application/MyApp.MyModel.1.0+json • Your API server should check the

    “Accept” header and instantiate that version of response top level model. 1.0 in this case. • Fill in your model with information from various tables (de- normalization) • Serialize version 1.0 of your top level model as your response Versioning - Right way
  18. Why version your models? • Ensures that changes to database

    doesn’t affect the response • The server developer will have complete control over when to deprecate a certain top level model’s version. • That is, if some change made to the database can no longer be meaningfully accommodated into the top-level model, you can deprecate it. • Changes to DB can be done with less impact. This means your server, and hence you startup will be more nimble (and even pivotable) to changes.
  19. Caching • Most of you think caching is something that

    clients should implement • Client has no way to know when to expire or revalidate • Example • User Profile avatar update • A client remembers a profile image for 7 days • Any changes to avatar will not be visible on client for the next 7 days
  20. • HTTP 1.1 spec standardizes the following cache control headers

    • Expiration Model • Expires • Cache-Control • Validation Model • ETag • Last-Modified Caching
  21. Caching - Validation Model • Checksum of the resource •

    Sent as ETag • Last-Modified (if you database has this info) • Sent as Last-Modified Or Cache-Control
  22. Caching - Server side implementation • ETag based caching is

    easy • Hash the top-level-object using any object hashing algorithm • Last-Modified • Server should send data that was new after IF-MODIFIED-SINCE select * from friends becomes, select * from friends where friendedDate > IF-MODIFIED-SINCE
  23. Choosing a caching model • All static resources - Expiration

    model • All dynamic data - Validation model • If dynamic data is a list - Use Last-Modified based validation model • Example - /friends • If dynamic data is a model - use ETag based validation model • Example - /user/<uid>/avatar
  24. Resources • Books • REST API Design Rulebook, By Mark

    Masse http:// shop.oreilly.com/product/0636920021575.do • Web Resources • http://blog.mugunthkumar.com/articles/restful-api-server- doing-it-the-right-way-part-1/ • http://blog.mugunthkumar.com/articles/restful-api-server- doing-it-the-right-way-part-2/
  25. Thanks @mugunthkumar [email protected] iostraining.sg Available for consulting services iOS App

    Development API/Server Design Mobile UX ROB NAPIER MUGUNTH KUMAR Advanced Application Development for Apple iPhone®, iPad® and iPod® Touch PUSHING THE LIMITS iOS 5 PROGRAMMING
  26. iOS Conf SG - 2013 • 31st Jan - Workshop

    and Hands On • 1st Feb and 2nd Feb - Conference • 15 Awesome Talks by renowned iOS Developers around the World • Join us at @iosdevscout or @iosconfsg • http://facebook.com/groups/iosdevscout/