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

2. About me
ROB 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 iOS
iOS 5 programming at iOSTraining.sg.
PROGRAMMING • 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. Agenda
• HTTP Verbs
• API Documentation
• De-normalization
• Versioning and deprecation
• Caching

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

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. 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. 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. 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. 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

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. 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. 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. 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. 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. 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. 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. 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. 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. Don’t do this!
$var = mysql_query(“select * from User”);
json_encode($var);

22. Caching

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. Caching
• HTTP 1.1 spec standardizes the following cache control headers
• Expiration Model
• Expires
• Cache-Control
• Validation Model
• ETag
• Last-Modified

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

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. Caching - Client validation
Important HTTP Headers
• IF-MODIFIED-SINCE
• IF-NONE-MATCH

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-SINCE
select * from friends
becomes,
select * from friends where friendedDate > IF-MODIFIED-SINCE

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

31. Thanks
@mugunthkumar
ROB NAPIER MUGUNTH KUMAR
mugunth@steinlogic.com
iostraining.sg
iOS 5
PROGRAMMING Available for consulting
PUSHING THE LIMITS
services
Advanced Application Development
for Apple iPhone , iPad and iPod Touch
® ® ®
iOS App Development
API/Server Design
Mobile UX

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
• http://facebook.com/groups/iosdevscout/