[RFC] Add jsonapi features: sparse fieldset & compound document to /surveys

[sleepylee]

Why

I found a few sets of json:api features that could be enabled on our API which could enhance the performance.

Sparse fieldset

Just like Graphql, JSON:API spec was built with a performance purpose in mind, one could help provide a faster response is to giving only what the users want and avoiding fetching unrelated data from another table.
It is one of the first to introduce (in order) features from JSONAPI example.

As been proposed to be an optional/advanced feature, the current way of calling our API should work in a backward compatibility manner.

Suggestion:

• Add handler for extra params: fields[survey]=title,description,... and respond only the corresponding record/fieldset.
• In case fields is not specified, we can return the previous format, which means including relationships with question data from the root table...

Benchmark:

Since we are not arbitrary serialize the question from the other table (serving by default when defining has_many:), and only request for specific fields, the data structure is cleaner and faster response compared to the previous result:

With fields

Without fields

You can see the result from the Transfer Start & Download stats 🤔

Compound Document

From the same JSONAPI example, it's simply like the way we are adding question data to the included node when searching a survey detail by id.

When adding include capacity to surveys/ - definitely it will take longer to process.

But there could be a use case from the client consumer that they want both survey + question detail at once (maybe to cache locally without calling making arbitrary calls to fetch all the questions under each survey? 🤷 ).
As it is an optional feature, the client could decide to opt-in or just have the basic set of survey details as-is.

Suggestion:

• Add handler for extra params: include=questions and respond only the queried data to the included node.
• In case include is not specified, the API returns like the previous format, which means not including included by default.

Who benefits?

Definitely the frontend devs 😄 As these are some extra features built on top of what we are currently having, I think devs will not mind advancing their usage for the performance purpose 🙃

Let me know your thoughts, I already prepared a branch for a PR if it is approved for this /surveys API 🙋‍♂️ :

• Add sparse fieldset support: ✅ / ❌
• Add compound document support: ✅ / ❌

[hoangmirs]

That is a good idea. We normally don't use this because when designing an API, we defined which fields need to return.
But the JSON:API format can support this, so having this extra feature is good. I hope you push the PR soon 👍