We have e-commerce websites for mobile phones. We are building restful api to POST,PUT,DELETE,UPDATE mobile phones.

Every mobile phone will have basic features like:- price, manufacturer, year of manufacturing, color, discount.

Along with this, most of the mobiles will have images too.

Additionally few of these have manufacturer warranty. Lets say 50% of them.

And few of mobiles will have finance options available, like we have tie up with certain banks to facilitate loan for these. Almost 80% will have this facility.

We were deciding two approaches to design api for this:

Approach 1. All of these in the same JSON object. Just one API like:

    "basicInfo": {
      "price": "",
      "mfgYear": "",
      "manufacturer": ""

Approach 2. Have all of these JSON object separately. For example:

First Api for "basicInfo".
Second Api for "images".
Third Api for "warranty".
Fourth Api for "finance" I could figure out few pros and cons of each:

APPROACH1: Pros: We get all information of stock together on server. That means less API hits, less load on server. Also, in future if we implement some queue processing to save these stock information to database, there would be no case of image/warranty/finance being posted before the stock is inserted into the database as we have all information together here. So we will first insert stock into the database and then insert record into other tables which will have Foreign Key relationship. Cons: This API/resource has multiple responsibilities. It would become bigger and bigger and there may be too many fields in this API in future. Also this looks like violation of Single Responsibility principle to me.

APPROACH2: Pros: This looks bit cleaner and organized. Looks like each API has its own responsibility defined. Looks scalable to me. If change is made in one API, it is less likely to affect the other APIs. Cons: More number of API hits on server. Greater chances of dependent resources of stock being posted before stock is posted. For example we may dequeue images before stock in inserted.

Approach3. Giving both the options. Example allowing to send other info with basic info as well as creating separate APIs for these resources.

Which is the best approach, i.e. more restful, scalable and better performance wise?

  • I'm not saying approach 1 wouldn't scale, but approach 2 definitely looks like it could scale a lot better. What if you decide to host multiple financing partners or mobile plans for some phones? What if there's this one radical phone with so many physical features it's going to need twice as much images? Especially when you consider you might pull financing data from different providers, the initial (in approach 1) request might take too long. The design of APIs generally tends to lean to small, single-responsibility, micro-services nowadays. Feb 21, 2017 at 7:21
  • Already asked by this user at stackoverflow.com/questions/42354409/…
    – Eric Stein
    Feb 21, 2017 at 12:47

2 Answers 2


One of the principles of a REST interface is that the consumers should not be required to have intrinsic knowledge where to find related information to a resource they have just retrieved.
This means that if I just retrieved a Phone resource from http://example.com/phones/42, I should not need to know if the images are located at http://example.com/phones/42/images, or http://example.com/phone_images/42, or somewhere else.

To avoid putting such knowledge in the consumers of the interface, a combination of your approach 1 and 2 is used: The basic resource representation contains links to the locations where additional information (such as images, financial options, etc.) can be retrieved. That way, the JSON structure does not get too bloated (especially with images that are not really suited for transfer in JSON anyway), and the client doesn't have to guess where to retrieve the additional information if and when they need it.

  • Thats fine with GET of a resource. But for the question is about POST/PUT of such resources, should there be one big Api OR multiple small APIs OR both should be there?
    – maverick
    Feb 21, 2017 at 8:57
  • @sahil: For PUT/POST, in principle the same holds, but there it seems to be a bit more accepted that the consumer knows which sub-resources (can) exist, so that you can do a POST to, for example, example.com/phones/42/images to add an image to an existing phone without it being explicitly advertised that phone images go there.. Feb 21, 2017 at 10:21

If you want you API to be RESTful, it must be stateless by definition.

Approach 2 is not stateless in the sense that in order to get all the information you have to issue several requests that have to be pieced together afterwards, i.e. depend on each other.

In order to get a clean interface you might want to take a look at jsonAPI.org, which defines a specification for writing APIs using json.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.