Designing your API Server for mobile apps


Published on

Published in: Technology
1 Comment
No Downloads
Total views
On SlideShare
From Embeds
Number of Embeds
Embeds 0
No embeds

No notes for slide

Designing your API Server for mobile apps

  1. 1. Designing Your API Server Mugunth Kumar iOS Developer, Author and Trainer
  2. 2. About meROB NAPIER MUGUNTH KUMAR • 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 iOSiOS 5 programming at • Developer PUSHING THE LIMITS • MKNetworkKit (1100+ watchers)Advanced Application Development • MKStoreKit (700+ watchers)for Apple iPhone , iPad and iPod Touch ® ® ® • Several other “minor” projects with 200+ watchers • Clients include startups in Singapore like Squiryl, Found and MNC’s including Microsoft Redmond, Oracle and such.
  3. 3. Agenda• HTTP Verbs• API Documentation• De-normalization• Versioning and deprecation• Caching
  4. 4. 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
  5. 5. 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
  6. 6. 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 op=“get_profile”
  7. 7. 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.
  8. 8. 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.
  9. 9. 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”
  10. 10. 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
  11. 11. Documentation• Example:• /venue• accepts a venue id• returns a detailed venue object• App.NET (That “upcoming” $50 social network)• Twitter - Extensive and difficult to understand though
  12. 12. 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
  13. 13. 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
  14. 14. 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
  15. 15. 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.
  16. 16. 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
  17. 17. 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”} ?
  18. 18. 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
  19. 19. Versioning - Right way• 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
  20. 20. 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.
  21. 21. Don’t do this!$var = mysql_query(“select * from User”);json_encode($var);
  22. 22. Caching
  23. 23. 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
  24. 24. Caching• HTTP 1.1 spec standardizes the following cache control headers • Expiration Model • Expires • Cache-Control • Validation Model • ETag • Last-Modified
  25. 25. Caching - Expiration Modellocation ~ .(jpg|gif|png|ico|jpeg|css|swf)$ { expires 7d; } Expires: <date>
  26. 26. 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
  27. 27. Caching - Client validationImportant HTTP Headers • IF-MODIFIED-SINCE • IF-NONE-MATCH
  28. 28. 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-SINCEselect * from friendsbecomes,select * from friends where friendedDate > IF-MODIFIED-SINCE
  29. 29. 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
  30. 30. Resources• Books • REST API Design Rulebook, By Mark Masse http://• Web Resources • doing-it-the-right-way-part-1/ • doing-it-the-right-way-part-2/
  31. 31. Thanks @mugunthkumarROB NAPIER MUGUNTH KUMAR iostraining.sgiOS 5PROGRAMMING Available for consulting PUSHING THE LIMITS servicesAdvanced Application Developmentfor Apple iPhone , iPad and iPod Touch ® ® ® iOS App Development API/Server Design Mobile UX
  32. 32. 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•