Best practices for API design for an E-Commerce System

Question

I have a few basic questions on how to implement an API for a basic e-commerce system.

The relevant entities are Customer, Puffle, and Review. Each Puffle can have zero or more Reviews. Each Review is authored by a Customer.

Currently, I have the following relevant endpoints:

• /catalog which returns all Puffles with the form

{
  "content": [
    {
      "id": "280d7907-c4e7-486a-9e81-8226894451be",
      "description": "a",
      "name": "a",
      "price": 1.00,
      "type": "a",
      "brand": "a",
      "quantity": 1,
      "rating": 2.0,
      "links": [
        {
          "rel": "self",
          "href": "http://localhost:8080/catalog/280d7907-c4e7-486a-9e81-8226894451be"
        },
        {
          "rel": "reviews",
          "href": "http://localhost:8080/catalog/280d7907-c4e7-486a-9e81-8226894451be/reviews"
        }
      ]
    }
  ],
  "pageable": {
    "sort": {
      "empty": false,
      "unsorted": false,
      "sorted": true
    },
    "offset": 0,
    "pageNumber": 0,
    "pageSize": 10,
    "paged": true,
    "unpaged": false
  },
  "last": true,
  "totalPages": 1,
  "totalElements": 3,
  "first": true,
  "size": 10,
  "number": 0,
  "sort": {
    "empty": false,
    "unsorted": false,
    "sorted": true
  },
  "numberOfElements": 3,
  "empty": false
}

• /catalog/{id}, which returns just a single Puffle

• /catalog/{id}/reviews, which returns all the reviews for a given Puffle in the following form:

{
   "content":[
      {
         "id":"71bb79fd-9fb5-4d74-8f9f-d9b3171af6a8",
         "puffleId":"280d7907-c4e7-486a-9e81-8226894451be",
         "customer":{
            "name":"Richard Robinson"
         },
         "content":"hello",
         "rating":2,
         "createdAt":"2022-03-19T04:23:07.775+00:00",
         "links":[
            {
               "rel":"self",
               "href":"http://localhost:8080/catalog/280d7907-c4e7-486a-9e81-8226894451be/reviews/71bb79fd-9fb5-4d74-8f9f-d9b3171af6a8"
            },
            {
               "rel":"customer",
               "href":"http://localhost:8080/customers/c8c80f8f-31d3-4484-bd47-29762d5da8cd"
            }
         ]
      }
   ],
   "pageable":{
      "sort":{
         "empty":false,
         "sorted":true,
         "unsorted":false
      },
      "offset":0,
      "pageNumber":0,
      "pageSize":10,
      "paged":true,
      "unpaged":false
   },
   "last":true,
   "totalPages":1,
   "totalElements":1,
   "first":true,
   "size":10,
   "number":0,
   "sort":{
      "empty":false,
      "sorted":true,
      "unsorted":false
   },
   "numberOfElements":1,
   "empty":false
}

Now, as for my design questions:

1. Should the reviews path be what I have currently (/catalog/{puffle_id}/reviews/{review_id})? Especially since when specifying the review id, the Puffle id isn't actually being used since the review id is just looked up in the reviews tale. However, for /catalog/{puffle_id}/reviews, the Puffle id is needed.

2. Currently, the review response body only contains a subset of the fields of the customer that authored it. Should it remain as is, contain all the fields of the customer, or contain no fields of the customer and instead just have the customer id as a field of the review response body? I can see arguments for all three ways and I'm not sure which is best practice.

3. For the review response body links, should it or should it not contain an href link to the customer resource? I feel like it should, however doing so requires the Catalog controller to access the Customer controller, which feels really wrong. So, what's the best practice in this case? And in general what are the best practices for HATEAOS?

4. Likewise, should the puffle response body links contain an href link to its reviews like it does currently? Or not?

Thank you very much

Answer 1

May I recommend to develop API based on business operations? For example:

• getCatalog(catalogId):Catalog
• getReviewsForCatalog(catalogId):ListOfReviews
• describe models for apis (what are Catalog and Review)

and so on. You want to decouple protocol (rest, soap, etc) from actual API's.

With this api's in hands, you can validate them by pseudo code clients - will your customers be able to do their job using your apis? Are your apis easy to use?

Doing this modelling and then proofing with actual use cases will help you to answer your questions.

I avoided answering your questions for this specific reason - I don't know how your clients will use your system; hence I can't give a good advise.

Answer 2

1. Should the reviews path be what I have currently (/catalog/{puffle_id}/reviews/{review_id})? Especially since when specifying the review id, the Puffle id isn't actually being used since the review id is just looked up in the reviews tale. However, for /catalog/{puffle_id}/reviews, the Puffle id is needed.

If the review id is globally unique (you don't need to know the Puffle to access the review), then you can use either /catalog/{puffle_id}/reviews/{review_id} or /reviews/{review_id}. You can even support both (with the first one redirecting to the second). That is entirely up to you.

2. Currently, the review response body only contains a subset of the fields of the customer that authored it. Should it remain as is, contain all the fields of the customer, or contain no fields of the customer and instead just have the customer id as a field of the review response body? I can see arguments for all three ways and I'm not sure which is best practice.

The "best practice" is to look at the typical way that a review response will be used and to avoid the front-end having to perform multiple requests where a single one could have been sufficient.

If the review is typically shown to the user with some basic information about the customer who wrote the review, then it makes sense to include that basic information in the review response, but including the full information would be overkill and unnecessarily increase the required bandwidth.

3. For the review response body links, should it or should it not contain an href link to the customer resource? I feel like it should, however doing so requires the Catalog controller to access the Customer controller, which feels really wrong. So, what's the best practice in this case? And in general what are the best practices for HATEAOS?

4. Likewise, should the puffle response body links contain an href link to its reviews like it does currently? Or not?

If you want to follow HATEAOS, then those links to the Customer (from the review) and to the reviews (from the puffle) should be in. You are even missing a link from the review back to the puffle..

One of the principles in HATEAOS is that the client does not have any knowledge about how a link it has could be changed to create another valid link. The client only knows how to follow links that are provided to it.