Notes On Mobile API Design

Yesterday, I watched great talks on API design from the API Strategy and Practice Conference (APIStrat) earlier this year. Two of the talks really stood out – the one by iOS Engineer Michele Titolo and the one by Etsy Engineer Paul Wright, as they really focused specifically on Mobile API Design.

As a Mobile Engineer it is my job to work closely with the API creators to make sure the end user has the best experience on mobile. Unfortunately, it is usually an up-hill battle as the API creators want to have a clean RESTful API, while that is not always the right thing for mobile, or, worse, a mobile-friendly API is not a big priority to them.

Anyway, I wanted to point out some great takeaways for API designers from Michele and Paul’s talks:


The mobile API needs to be FAST!!!! According to Michele, a user is willing to wait for only a maximum of 300ms for something to happen!

The 300ms includes:

  • making the request
  • processing the response
  • showing the results to the user

REST might not be best

According to Paul, the previous version of the Etsy API resources mirrored the database schema. So when the client got a list of listings, they needed to do another api call on the user resource to get all the listing ids that the user favorited.

The more API calls the client needs to make, the slower the client will be. In addition, there is a huge risk of having multiple points of failure. What if the listings call comes back, but the favorites doesn’t because the user just drove under a tunnel and lost connectivity? As Michele mentions, having multiple calls on each mobile screens creates some serious syncing problems and complex logic on the client.

Same goes for saving an object. If a user is displayed a list of objects on the client, and they edit all of them at the same time, there needs to be one call to the api to save all the listings at the same time instead of multiple calls to save each individual listing. If only one listing at a time is saved, there is a big chance at least one of the listings will fail to save, and now the client and the database data are out of sync!

The API should be driven by user experience. The rule is: 1 screen, 1 API call. 1 save, 1 API call.

The new version of the Etsy API now focuses on Domain Resources that are independent from the database schema resources. So if a user requests a listing, the image url for the listing will come back as part of the listing, since the client very likely needs it. As a result, the new resource objects are a lot fatter, returning data that would previously take 5 API calls to get with the previous more RESTful API.


Different clients have different needs, so the API needs to be flexible. Again, part of this means relaxing the REST constraints.

The new Etsy API has “Bespoke” endpoints – the client can specify as many resources as they need in their API call, and the server does the work of concurrently fetching the resources from the database and combining the data into one response back to the client. To the client, it’s 1 screen, 1 call. On the server, it’s multiple calls done concurrently, so the API is still fast.

As Michele mentions, products change over time, so app functionality will change. Making the API flexible from the start means those future changes can happen a lot faster.

Handle 3rd Party APIs on Server

Let’s say you have a user action that triggers an email via the Sendgrid API. The actual API call to send the email via Sendgrid, a 3rd  party, should be done on the server as Michele mentions. Otherwise, if you have an iOS, Android, and a Web App, the logic to call the Sendgrid API is now in 3 different places! If Sendgrid has some downtime, now each client has to deal with that scenario. When Sendgrid upgrades their API, each client will need to do the same upgrade.

And worse, when the user downloads their app with that version of Sendgrid API, they might never upgrade to a newer app with the newer Sendgrid API version (just think of all the Android Gingerbread user!) – so now you’re screwed when Sendgrid decides to deprecate a version of their API from 2 years ago.

If there is a bug with your implementation of the Sendgrid API on the iOS client in production, you won’t be able to provide a fix for possibly over 2 weeks on iOS – since you’ll have to wait for Apple to approve the new version of your app with a bug fix!

All these issues can be handles seamlessly and in real-time on the server!

Version Based on Payload

The API versioning should be based on Payload, since that is what will actually break the client. Non-breaking changes, such as making the API faster doesn’t need to be versioned – it’s great for all versions of the API to be faster!

This means that you can Optimize Later according to Michele. Agree on the API payload first, so the client developer can start working on their end right away, then optimize the database queries and make the api fast later. These changes will not break the client, but it will let the client build fast and the server to optimize at the same time.

Business Logic on Server

When you have 3 clients (web, ios, android) and possibly more in the future (iWatch?), it becomes very obvious that the complex business logic should be kept on the server.

For example, the previous Etsy API would return different payloads based on whether the user making the request was a public user, a member, or a shop. The client had to add complex logic to figure out which fields to display for each user type. Now, the API does the complex logic and just returns the user object that is easy to work with on the client.

The other great side-affect of doing this is that when the business logic changes – the executive decides the user’s password should be 8 characters instead of 7 – that logic is changed once on the server and immediately applies to all clients.


Although the mobile app might start out as an Minimum Viable Product (MVP), the goal should be to build out a full-featured applications. Users expect to do everything they do on the web on mobile.

This means that the API needs to be full-featured. Even if some of the API calls are not used today, when the client or project manager asks “can we…”, if the API is there, we can! As Michele points out, mobile should have the flexibility to consume whatever it needs.

The Full Video

Here is the full video from APIStrat. Michele’s talk is fist, and Paul is at 20:45.

Do you have any additional mobile API design tips? Leave them in the comments!

Enjoy the article? Join over 20,000+ Swift developers and enthusiasts who get my weekly updates.