Efficiency of RESTful APIs

Question

I'm currently creating an application (let's say, notes app, for instance - webapplication + mobile app). I wanted to use RESTful API here, so I read a lot about this topic and I found out there's a lot of ambiguity over there.

So let's start at the beginning. And the beginning in REST is that we have to first request the / (root), then it returns list of paths we can further retrieve, etc, etc. Isn't this the the first part where REST is completely wasteful? Instead of rigid paths, we have to obtain them each time we want to do something. Nah.

The second problem I encountered was bulk operations . How to implement them in REST? Let's say, user didn't have access to the internet for a while, made a few changes and they all have to be made on server as well. So, let's say user modified 50 notes, added 30 and removed 20. We have to make 100 separate requests now. A way to make bulk operations would be very helpful - I saw this stackoverflow topic: Patterns for handling batch operations in REST web services? but I didn't found anything interesting here actually. Everything is okay as long as you want to do one type of operation on one type of resources.

Last, but not least - retrieving whole collection of items. When writing an example app I mentioned - notes app - you probably want to retrieve all collection of items (notes, tags, available notes colors, etc...) at once. With REST, you have to first retrieve list of item links, then fetch the items one by one. 100 notes = over 100 requests.

Since I'm currently learning all this REST stuff, I may be completely wrong at what I said here. Anyway, the more I read about it, the more gruesome it looks like for me. So my question finally is: where am I wrong and/or how to solve problems I mentioned?

Answer 1

It's all about resources . Resources that are obtained through a uniform interface (usually via URI and HTTP methods).

1. You do not have to navigate through root every time. A good interface keeps their URIs alive forever (if they go stale, they should return HTTP Moved or similar). Root offering pathways to navigate is a part of HATEOAS , one of Roy Fieldings defined architectural elements of REST.
2. Bulk operations are a thing the architectural style is not strong on. Basically nothing is stopping you to POST a payload containing multiple items to a specific resource. Again, it's all up to what resource you are using/offering and ultimately, how your server implementation handles requests. Your case of 100 requests: I would probably stick with 100 requests. It is clean to write and the overhead is not that huge.
3. Retrieving a collection: It's about resources what the API decides to offer. GET bookCollection/ vs GET book/1 , GET/book/2 ... or even GET book/all . Or maybe GET book/?includeDetails=true to return all books with same detail as GET ting them one-by-one.

Answer 2

I think that this link could give you interesting hints to design a RESTful service: https://templth.wordpress.com/2014/12/15/designing-a-web-api/ .

That said, here are my answers to your questions:

• There is no need to implement a resource for the root path. With this, I think that you refered to HATEOS. In addition, no link within the payload is also required. Otherwise you can use available formats like Swagger or RAML to document your RESTful service. This show to your end users what is available.

• Regarding bulk operations, you are free to use methods POST or PATCH to implement this on the list resource. I think that these two answers could be helpful to you:

  • REST API - Bulk Create or Update in single request - REST API - Bulk Create or Update in single request

  • How to Update a REST Resource Collection - How to Update a REST Resource Collection

• In fact, you are free to regarding the content you want for your methods GET . This means the root element managed by the resources (list resource and element resource) can contain its hints and also the ones of dependencies. So you can have several levels in the returned content. For example, you can have something like this for an element Book that references a list of Author :

   GET /books { "title": "the title", (...) "authors": [ { "firstName": "first name", "lastName": last name" }, { (...) }, (...) ] } 

  You can notice that you can leverage query parameters to ask the RESTful service to get back the expected level. For example, if you want only book hints or book hints with corresponding authors:

   GET /books { "title": "the title", (...) } GET /books?include=authors { "title": "the title", (...) "authors": [ { "firstName": "first name", "lastName": last name" }, { (...) }, (...) ] } 

  You can notice that you can distinguish two concepts here:

  • The inner data (complex types, inner objects): data that are specific to the element and are embedded in the element itself
  • The referenced data : data that reference and correspond other elements. In this case, you can have a link or the data itself embedded in the root element.

  The OData specification addresses such issue with its feature "navigation links" and its query parameter expand . See the following links for more details:

  • http://www.odata.org/getting-started/basic-tutorial/ - Section "System Query Option $expand"
  • https://msdn.microsoft.com/en-us/library/ff478141.aspx - Section "Query and navigation"

Hope it helps you, Thierry