Description
Currently, there are multiple endpoints for which multiple requests are necessary to get information. Following REST principles, we should structure our endpoints similarly to files in a file system. This presents a challenge when users want to get information about user roles for example. Currently, if you want information about a user's roles, you have to look up their entire profile and get all of their information just to get a roles field as an array of role IDs. This is not only wasteful for bandwidth, but a waste of time for users, as they now have to query /v2/roles/{role_id} for every role in that array.
Possible Solutions
JSON Path-based Selection
The API would allow users to select specific fields using a with_field query with a URL encoded form of RFC 9535 as its value. This would allow for less wasteful bandwidth, and it would allow for a simpler implementation. However, it may confuse users of the API as, when compared to other REST APIs, this format is quite complicated and requires URL encoding.
Endpoint-specific Field Selection
Similar to JSON Path-based Selection, this proposal would add a with_field query. However, the query would have specific, endpoint-defined fields. This unnecessarily complicates the implementation as each Endpoint would be required to implement field selection logic in some manner (even if abstracted away by a method), and it would .
Per-field Value Expansion
Parallel to the other proposals, this proposal would add a with_{field_name} query which allows for individual fields to be expanded to full values or collapsed to IDs where applicable. The immediate downside would be complicating the implementation by requiring more complicated endpoints to switch on each applicable field. However, API users would be able to more easily get relevant information with fewer HTTP queries.
Sylv's Proposal
JSON Path-based Selection with Per-field Value Expansion is, in my opinion, the best compromise in terms of implementation complexity and API usability. However, considering the extra burden on testing, it may be better to abandon field selection and just focus on more granular value expansion.
Description
Currently, there are multiple endpoints for which multiple requests are necessary to get information. Following REST principles, we should structure our endpoints similarly to files in a file system. This presents a challenge when users want to get information about user roles for example. Currently, if you want information about a user's roles, you have to look up their entire profile and get all of their information just to get a
rolesfield as an array of role IDs. This is not only wasteful for bandwidth, but a waste of time for users, as they now have to query/v2/roles/{role_id}for every role in that array.Possible Solutions
JSON Path-based Selection
The API would allow users to select specific fields using a
with_fieldquery with a URL encoded form of RFC 9535 as its value. This would allow for less wasteful bandwidth, and it would allow for a simpler implementation. However, it may confuse users of the API as, when compared to other REST APIs, this format is quite complicated and requires URL encoding.Endpoint-specific Field Selection
Similar to JSON Path-based Selection, this proposal would add a
with_fieldquery. However, the query would have specific, endpoint-defined fields. This unnecessarily complicates the implementation as each Endpoint would be required to implement field selection logic in some manner (even if abstracted away by a method), and it would .Per-field Value Expansion
Parallel to the other proposals, this proposal would add a
with_{field_name}query which allows for individual fields to be expanded to full values or collapsed to IDs where applicable. The immediate downside would be complicating the implementation by requiring more complicated endpoints to switch on each applicable field. However, API users would be able to more easily get relevant information with fewer HTTP queries.Sylv's Proposal
JSON Path-based Selection with Per-field Value Expansion is, in my opinion, the best compromise in terms of implementation complexity and API usability. However, considering the extra burden on testing, it may be better to abandon field selection and just focus on more granular value expansion.