The ‘attributes’ keyword is an unusual choice for output selection. Sparse fieldsets (‘fields’) is a flexible, widely used and well understood mechanism (Google, JSON-API), and is used in the previous DTA API standards, the WhiteHouse API standards and the NZ gov API standards. The fields keyword does not rely on dependant keywords, and 'plays nicely' with multiple independent parameters. I would like to gauge the opinion of the working group on the choice of keyword.
Suggested change:
Output Selection
Consumers can specify the fields they wish to return in the response payload by using the 'fields' keyword in the query parameters.
Example that returns only the first_name and last_name fields in the response.
?fields=first_name,last_name
The ‘attributes’ keyword is an unusual choice for output selection. Sparse fieldsets (‘fields’) is a flexible, widely used and well understood mechanism (Google, JSON-API), and is used in the previous DTA API standards, the WhiteHouse API standards and the NZ gov API standards. The fields keyword does not rely on dependant keywords, and 'plays nicely' with multiple independent parameters. I would like to gauge the opinion of the working group on the choice of keyword.
Suggested change:
Output Selection Consumers can specify the fields they wish to return in the response payload by using the 'fields' keyword in the query parameters. Example that returns only the first_name and last_name fields in the response. ?fields=first_name,last_name