search

apigovau / national-api-design-standards

Australian National API Design Standards
35 stars 15 forks source link

query-parameters.md standards alignment #53

Closed TimGoodwill closed 3 years ago

TimGoodwill commented 4 years ago

Update query-parameters.md filtering and output selection keyword to align with previous DTA standards and current international gov API standards.

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. ‘filter’ (rather than 'filters') is a prevalent industry standard (Microsoft, Google, OData), and should use OData syntax to support existing filter string parsing libraries, negate the need to escape reserved chars, and disambiguate the '=' char. Issue #25 Issue #42 Issue #43

ghost commented 3 years ago

Good to see references to oData querying syntax for the Advanced Filtering, but all filtering should follow the industry OData 4.0 standard.

We really shouldn't be creating our own bespoke non-interoperable standard. It would be better to abstain if there is no consensus to use OData

TimGoodwill commented 3 years ago

Good to see references to oData querying syntax for the Advanced Filtering, but all filtering should follow the industry OData 4.0 standard.

Updated to ref OData 4.0

We really shouldn't be creating our own bespoke non-interoperable standard. It would be better to abstain if there is no consensus to use OData

There is no impediment to individual agencies implementing OData in its entirety, however that is a huge commitment. Certainly embedding the OData standard is a discussion for another phase. This is an amendment is to ensure that if limited complex filtering is to be offered, the filter keyword and syntax is broadly compatible with OData and common practice.