Avoid compound documents?

1

Working on a new project with jsonapi, and the backend has requested that we no longer support compound documents as they’re a performance issue for backend. http/2 has been given as the solution, but I have concerns about requesting duplicate resources, caching, waterfall relationships, etc. Does anyone think compound documents should always be avoided? Are there resources for what the caveats might be?

2

Not using compound documents at all means not taking advanced of ones of the most advanced features of JSON:API. Compound documents together with include query param gives you one of the features which made GraphQL such famous: “Ask for what you need, get exactly that”.

Compound documents might have a bad impact on APIs workload in some scenarios:

  • API might include related documents by default even if the client did not requested to do so. In that case reading these data from database isn’t necessary and increases the workload. Also payload size is increased without a need. This is only an issue if API includes related documents even if client didn’t passed an include query param.
  • If there are requests for a resource with and without include query param a HTTP proxy hit rate might be less than without supporting include query param.

There shouldn’t be a bad impact for API workload if the client is only doing one request for a compound document compared to several requests to fetch related resources individually. The API has to fetch the same data from database and has to serve the same amount of data. Actually it might be worse to serve the same data with 2 requests (one for the main resource and one for it’s relationship link) than with on due to work needed to serve an individual request.

It has a bad impact on client performance in the most use cases as the requests can’t be done in parallel. The client must wait for the request for the main resource to fulfill before it can start a request for the related resources. HTTP/2 doesn’t make any difference for this. It just reduces the costs of additional requests and makes executing them in parallel faster.

Having that said there might be edge cases in which an API does not want to support compound documents / include query param for some endpoints. E.g. the resources might be handled by different microservices and including them in a compound document would require tight coupling of the microservices which should be avoided.