Currently “fields” is used for limiting what is returned, what if I want to add to what is returned?
For example, take an Order resource that has 10 default fields. Only for very specific requests do I want to include total_price, which can run an expensive algorithm (fetching all products within the order, adding up their prices, calculating tax, etc). Because this field is expensive, I don’t want it as a default.
Would it make sense to support an API like /orders?extra_fields[order]=total_price?
If I were to create a client for this, I would find it confusing. I would much prefer to get the whole resource back and then cherry pick.
I would consider moving the pricing to a related resource and make separate calls. The client can then have the choice of calling each independently or using include.
@brainwipe I hear you, I think getting the whole resource back by default is ideal. However, both including this field all the time or requiring separate calls don’t seem viable due to performance concerns.
I could create a related resource and use include, but personally I would find a resource-attribute with a fake id more confusing than something like extra_fields.
That would be the way I would do it. But if you don’t like that you could always create another resource. So you would have /orders/anorderid with the 10 default fields, and most clients / requests would go to that endpoint; but you could also have /totalledOrders/anorderid that also included the total_price attribute, and some clients / requests would go to this endpoint.
Note also that nothing in the spec prevents you from adding a custom query parameter like the extra_fields you described in your question. (See http://jsonapi.org/format/#query-parameters)