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:
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.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.
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?Likewise, should the puffle response body
links
contain an href link to its reviews like it does currently? Or not?
Thank you very much