REST API Design: How to break down the API object to make more scalable and robust API

api-designrest

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": ""
    ...
  }, 
    "images":{...},  
    "warranty":{...},    
    "finance":{...}    
   }

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?

Best Answer

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.

Related Topic