根据消费者请求构建 Rest API 响应 Object

Question

I am building rest API & below are my end points.

EndPoint 1:

/products/{code} --> giving product inforamtion

Endpoint 2:

/products/{code}/packages --> provides packages for a given productcode

Endpoint 3:

/products/{code}/suppliers --> provides suppliers for a given product code

Endpoint 4:

/products/{code}/shelfTags --> provides shelfTags for a given product code

We have multiple down stream systems(more than 20 downstream systems) which require products & it's related information.

Note: Not all users require the nested collection information, some clients need only product information and they are good and below are the combinations and it varies by consumers

1.  product info only --> **consumer 1**
2.  product ,  packages --> **consumer 2**
3.  product, suppliers, packages--> **consumer 3**
4.  product, supplier, packages, shelfTags--> **consumer 4**
5.  product, supplier, shelfTags --> **consumer 5**
6.  product, shelfTags --> **consumer 6**
7.  etc...

From above example, consumer 4 makes Http call to get product code and now has to make multiple Http calls to get packages (Endpoint 2) or suppliers (Endpoint 3) or shelfTags (Endpoint 4) etc... Is this a good design?

Is there a way consumers can get only what they want in response on one request? (Now is it a good design to give data needs in one request? or it's good to ask consumers to make multiple Http calls to get nested collection?)

Note: I cannot include all nested collection along with Products Endpoint 1 itself as it's requires huge data querying so I am planning to only provide what consumer may need, that will reduce unnecessary querying and also providing irrelevant information to few consumers who don't need that data.

Current Design:

I have below now:

Approach 1:

/products/{code}?Options = packages, Suppliers 

Above would give Product details and have options query parameter based on that I can decide whether to pass Packages & supplier, shelftags etc, but here we are not filtering on resource to pass query parameter, I believe this is not a good approach as query params are only used to filter on the resources.

Approach 2:

Form a different endpoint as query parameter on the resource is for only filters if I am not wrong so looking at below option:

/products/{code}/extendedProductDetails?Options = Packages, Suppliers

In option2 extendedProductDetails is an operation rather than resource itself and I am filtering on the operation.

Can anyone provide solution on how to solve this requirement

Answer 1

Approach 1 vs. Approach 2

Assuming that you want to use REST, from my point of view, between the options you gave, I would go with something like Approach 2 , since it is a proper collection for extended information. However, I think I'd prefer to model it such as /products-extended/{code}?options=packages,suppliers , since it defines a different collection.

Besides enhancing the readability of the API, in this way, you have the products collection and the products-extended collection: each of them can be consumed independently and with different query string filters (of course that less filtering is prone to increase complexity and latency, but in my opinion, query string parameters should be optional). If they must really not be optional and there is always the need to provide a product id and at least one nested collection, then, you can also consider designing something like products-extended/{code}/{packages,suppliers,etc} . Either way, this would "protect" your products collection.

Moreover, this would allow you to perform different operations (POST, PUT,...) to both collections, if your use case requires such.

Other approaches

Besides the other suggestions on GraphQL - would be great, yes:) -, OData or the custom types, couldn't you keep only with the individual collections? Depending on your use case, maybe you could perform parallel calls to /products/{code}/packages , /products/{code}/suppliers and so on, since you already know the product id . Perhaps, the major drawback of this design would be, for example, to create new products. However, the GET requests became super easy:)

Answer 2

Maybe a solution would be to use custom media types in the request header:

application/json+info-only
application/json+supplier
application/json+supplier+packages
etc.

In your controller action you would check for the selected media type and respond to the request based on them. Simply return an IActionResult and your consumer will get the data within one request.

It's very similar to your approaches but with custom extended media types you would have still one endpoint without additional parameters.