Project

Profile

Help

Story #2335

As an API consumer, I am able to discover filterable fields.

Added by semyers about 3 years ago. Updated 6 months ago.

Status:
CLOSED - DUPLICATE
Priority:
Normal
Assignee:
-
Category:
-
Sprint/Milestone:
Start date:
Due date:
% Done:

0%

Platform Release:
Blocks Release:
Backwards Incompatible:
No
Groomed:
No
Sprint Candidate:
No
Tags:
QA Contact:
Complexity:
Smash Test:
Verified:
No
Verification Required:
No
Sprint:

Description

In chatting with asmacdo about his filterset PR for Repository0, we were lamenting the lack of discoverability of the filter params. We'd love for autogenerated API clients to be able to know what filter options are allowed on a given view, and also to make sure the filter sets associated with a given API view show up meaningfully in the API docs that we generate.

[0]: https://github.com/pulp/pulp/pull/2783


Related issues

Duplicates Pulp - Issue #3635: Improve filter documentation by creating a BaseFilterSet class to automatically set filter help text MODIFIED Actions

History

#1 Updated by amacdona@redhat.com about 3 years ago

Not sure if this is the direction we want to go, but I hacked this up yesterday.

https://github.com/pulp/pulp/pull/2787

#2 Updated by semyers about 3 years ago

This is a poorly defined story, at the moment, because we know that we want to do as little work as possible to create API clients, the exact mechanism for achieving that goal has not yet been determined. Under the assumption that whatever mechanism we choose has the ability to express available URL query parameters for a given view, I think using the current OpenAPI standard (v2.00) as a guide is reasonable.

To that end, OpenAPI supports documenting available query params on endpoints:
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#parameter-object

So, we could potentially augment the existing openapi schema codec generator1 to make DRF include valid query params that our filter sets provide.

As far as documentation goes, that might do well as a separate story, but I'm not sure. asmacdo's approach in the previous comment is a great step in this direction, though.

[0]: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md
[1]: https://github.com/core-api/python-openapi-codec

#3 Updated by amacdona@redhat.com 11 months ago

  • Duplicates Issue #3635: Improve filter documentation by creating a BaseFilterSet class to automatically set filter help text added

#4 Updated by amacdona@redhat.com 11 months ago

  • Status changed from NEW to CLOSED - DUPLICATE

#5 Updated by daviddavis 6 months ago

  • Sprint/Milestone set to 3.0

#6 Updated by bmbouter 6 months ago

  • Tags deleted (Pulp 3)

Please register to edit this issue

Also available in: Atom PDF