Principle #11 – Partial Responses
cmheazel opened this issue · comments
• Allow the developer to fetch just not all the detail of a resource but select the fields of interest
• How to design the API to support this?
• Option 1: Integrate into path
– /v1/features/highways/A8:(name, geometry)
• Option 2: Use comma separated list as query parameter e.g. fields
– /v1/features/highways/A8?fields=name,geometry
• Advantage of option 2: It can be combined with other search options
– /v1/features/highways?id=A8&fields=name,geometry
Option 2 appears to be the more popular approach in RESTful frameworks such as Spring.io, NodeJS, OpenAPI etc.
I suggest removing Option 1 from the list.
I'm not sure option 2 will actually work. The HTTP Query works like an SQL Where statement. It serves to select elements for the result set based on attribute values. But, that does not mean that only the attributes referenced in the Query will be returned.
Please read and review the W3C work on profiles - this relates to named sets of properties and is highly relevant as a simple way to let clients get a set of information they need.
now addressed in master. With respect to W3C content negotiation by profile, and update can be considered after a stable draft.