Designing Your API Server Mugunth Kumar iOS Developer, Author and Trainer

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

Agenda • HTTP Verbs • API Documentation • De-normalization • Versioning and deprecation • Caching

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

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

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”

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.

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.

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”

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

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

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

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

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

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.

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

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”} ?

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

• 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

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.

Don’t do this! $var = mysql_query(“select * from User”); json_encode($var);

Caching

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

• HTTP 1.1 spec standardizes the following cache control headers • Expiration Model • Expires • Cache-Control • Validation Model • ETag • Last-Modified Caching

location ~ \.(jpg|gif|png|ico|jpeg|css|swf)$ { expires 7d; } Caching - Expiration Model Expires:

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

Caching - Client validation • IF-MODIFIED-SINCE • IF-NONE-MATCH Important HTTP Headers

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

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

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/

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

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/