Rest APIs - mobile specific challenges

Question

I'm working on a new iOS app project, on the mobile side. Some architecture changes are happening and it turns out we will have to rely on a custom built private API that will be used by the app we are building and also by other clients such as a website.

The API being designed follows the Rest style of resources-centric URI and CRUD operations mapped to HTTP verbs. things like:

GET www.example.com/books
DELETE www.example.com/books/482094
POST www.example.com/users/6793

The problem is that this style often leads to the need for the mobile client to do many requests for loading a single app screen or managing a single user UI action. This leads to the app being in loading mode for 8 seconds till it has everything needed. A slow and unresponsive app.

Mobile clients have serious limitations when it comes to connectivity and so ideally, we should follow that sort of rule:

1 screen == 1 API call

1 save == 1 API call.

There are many situations where this puts you on a collision course with the REST design principles, for examples:

• let's say your app has been offline for a day and you need to sync with four tables of the back-end databases and you need a call like www.example.com/sync_everything?since=2015-07-24
• let's say there is a screen where the user can edit many of his objects, for example ticking tasks in his todo list. There should be a way to edit all those tasks records in one single batch API call rather than one API call per edit.
• let's say there is a screen that mixes information from the ORDER, SALESMEN and PRODUCT db tables, I should get that data in one call instead of three.

the risk is that we might end up with the most Restful API there is and also the most useless unresponsive mobile app there is.

The thing is I'm only a new contractor there and what I need is something that help me makes those points, some articles from well respected sources or something like that. Major players compromising with the REST style for their mobile client (e.g.: by using composite aggregate API end points).

Or any solution for this general problem. Thanks!

Answer 1

The API being designed follows the Rest style of resources-centric URI and CRUD operations mapped to HTTP verbs.

This is your problem right here.

You have limited your resources to (I'm assuming) the models in your database. As such it is taking ages to load all these resources because your server has no concept of resources that don't have a representation in the database.

For example might have

www.example.com/books/482094
www.example.com/books/582045
www.example.com/books/427454
www.example.com/books/319343

that all have to be loaded to get my library

This isn't a problem with RESTful design, this is actual a REST anti-pattern. There is absolutely nothing in REST that says our resources must have a one to one mapping with anything else in your system, including database models.

The solution is to create more resources that better match what you want to load. If you have 5 resources that always end up together create a new resource that contains the info for those 5 resources.

What you should have is something like this

www.example.com/users/334/my_library

which just loads all the books for that user. "my_library" isn't a model in your database, but it is a resource. The server creates it based on models in the database but there is no 1-to-1 mapping and the server has flexibility to create this resource without changing your DB model.

You might also have

www.example.com/users/334/favioured_books
www.example.com/users/334/books_ordered_last_week
www.example.com/users/334/wishlist

none of which have to exist as model in your database or domain space.

There is a wide spread misconception that this is the wrong thing to do because frameworks like Rails taught people to map resources in a 1-to-1 fashion to models in the domain space which map again 1-to-1 with database rows. This is not necessary nor is it recommended.

Resources should be numerous, cheap and lightweight. It should be easy to create them, and they should be abstracted from your domain model. If you find you need a new one you just make a new one. If you have problems doing that it is your frameworks fault not a fault with REST.

Now the big caveat with that of course is whether your framework allows you to do this. Frameworks like Rails and Django which have taken the course to map 1-to-1 in order to "save you time" make it hard to do this. But that is a flaw with the frameworks, not with RESTful design.

Here is Jim Webber discussing this is more detail (including a few digs at Rails as well!)

https://yow.eventer.com/yow-2011-1004/domain-driven-design-for-restful-systems-by-jim-webber-1047