Is it OK to change the response depending on the GET request parameters?

Question

Would it be correct if the responses of one endpoint had a different set of fields?

For example:

There is the endpoint - /orders, which returns information about the orders (assume - 42 fields), and that information is displayed on the user's account web page.

At some point, we have another web page that needs (for its own purposes) information about orders that the user has not paid yet. The request would be something like this - /orders?unpaid=True In this case the web page needs only 4 fields instead of 42. Should i put only this four fields in the response or it would be better to keep one response format for any purposes?

Answer 1

There are no clear guidelines how to handle case like yours and all discussion seems to be quite opinion biased.

However, it seems that you intend to use query param unpaid to optionally filter out all paid orders so it is ok to put as query param in that sense.

But on the other hand it returns different kind of a response - even it might be a subset of a full (paid?) order data. In other words it makes your API a bit unclear if you decide to return different data types based on query param.

So I suggest the following approach:

/orders                       -- always data with 42 fields
/orderSummaries               -- always data with  4 fields
/orders?unpaid=True           -- always data with 42 fields
/orderSummaries?unpaid=True   -- always data with  4 fields

so let the query parameters affect only on filtering & sorting of the result set but not on the type of data you return.