CODEWITHSUNDEEP
restapiasp.net-web-apiapi-design
Sahil Sharma
Sahil Sharma

Reputation: 4237

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

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?

Upvotes: 1

Views: 1091

Answers (3)

Serhii Shushliapin
Serhii Shushliapin

Reputation: 2708

APPROACH1: Pros: [...] we will first insert stock into the database and then insert record into other tables which will have Foreign Key relationship.

If you want to build a robust API, than the way to go since it'll let you to perform the transaction safely.

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.

You can decrease the negative impact of this retrieving required fields only.

Upvotes: 0

Eric Stein
Eric Stein

Reputation: 13682

Given only the information you've provided, here's how I'd look at designing this system. Have separate endpoints for phones, warranties, and financing information. Aggressively cache warranties, because those will rarely change. Include links to the warranty and financing information in the phone's JSON representation. Have the /phones/{phoneId} endpoint support a query parameter named something like "expand". If the server sees expand=warranty, expand=financing, or expand=warranty, financing, embed the relevant JSON in the phone resource in addition to providing the links. Now clients can choose what information they need and get it.

For images, if possible use a CDN to take care of them and just include a link. If you need to manage them in your API, then I'd treat them the same as warranty and financing above. Make sure they're very aggressively cached, because what a phone looks like is not going to change very often. If you need to change the image, use a new filename.

An example of this approach can be seen in the specs for JSON API, where the relevant property is called "included". JSON API might be too heavy for you, but it has some good ideas and it's worth browsing the specs.

Finally, note that open-ended questions like this are more appropriate to https://softwareengineering.stackexchange.com/. Stack Overflow is intended for questions with a Correct Answer.

Upvotes: 1

RuDevel
RuDevel

Reputation: 714

I'm no pro with JSON, but AFAIK it's possible to stack those objects so you can have a hierarchical (full) push for inserts/updates and also complete (or intended incomplete) get- calls.

This way you don't have to blow up every push/pull action and are still flexible when it comes to extensions. You also can - or most probably want to - call specialized routines for insert/update of each of the sub- objects so you could possibly provide and use those as part of the REST API as well.

For the pull you could either mark missing nodes as undecided or already check against the DB and mark as either unloaded or not available.

Just keep in mind that if you provide an API for all sub- objects (APP.1 or 3) it will always be up to the caller to have those calls sorted- especially when it comes to deletions which usually are done in reversed order.

If you decide to go for the complex API (1 or 3) you can - however - still work with queues and timeouts. So you would store the requests (mainly writes) in queues and - after some short timeout - sanity check the queue before you forward the data to the insert/update(/deletion) routines.

Upvotes: 0

Related Questions