Strategies on documenting filter query format in OpenAPI spec

[geoff-maddock]

My team is working on an OpenAPI spec for a new API, and we're implementing a new filtering capacity for resources.

For example:
/entity?page=1&results_per_page=50&filters= column-a eq value-b, column-b neq value-b, column-c lte value-c

I'd like to be able to denote the available options for filters for ALL endpoints where filter is a possible query param, but not quite sure what the best approach would be, since the format is specific to filters.

Anyone have a suggestion or pattern for describing this?

[karenetheridge]

Isn't it just a simple matter of

/components:
  parameters:
    filter_parameters:
      - name: filter_parameters  # this name is arbitrary and not used anywhere
        in: query
        required: false
        schema:
          type: object
          properties:
            page:
              type: integer
              minimum: 1
            results_per_page:
              type: integer
              minimum: 1
            filters:
              type: string
/paths:
  /foo/{foo_id}/bar:
    parameters:
    - $ref: '#/components/parameters/filter_parameters'
    ...

Do you mean that the format of the filters string is different for every endpoint? If so you may wish to programmatically generate your specification and inline the filter parameters definition, swapping out the filters schema as needed.

[geoff-maddock]

In this case i mean the possible values for the right side of the filters: parameter, which would define the available values that could be put into a filters query.

EG: "possible values of filters include:
`column-a, column-b, column-c, custom-filter-d, custom-filter-e'

[handrews]

@geoff-maddock ah, I see. Currently there is no way to do that. Well... in OAS 3.1 you could exploit some obscure features by defining a media type for the query string that maps to the JSON data model and using contentMediaType and contentSchema... but I can't imagine any tools would do anything useful with that. A filter query langauge is too complex to fit any of the built-in serialization modes.

The problem with putting something like this in the spec is that everyone's query language is different. So whatever we picked would be usable only for a small percentage of people, which usually makes it very low priority for tooling vendors to support.

[geoff-maddock]

Yeah, understandable. I'm actually circling back to this problem that I posted about here in 2022. Mostly just trying to figure out how to indicate these filterable fields and custom filter options to the consumers of my API. Having a separate page is not ideal, but probably the option I'm going to land on for now. Putting them entirely in the description property of the filters property is also not ideal as some have 40+ filterable properties, but maybe logical.

[handrews]

You might also want to check out the OAI/sig-moonwalk repository, as that's where we're discussing what to do for 4.0, which will include more drastic revamps of pretty much everything. The "too-custom" problem still applies, but if there's a way to accommodate such things it is far more likely to be in 4.0.

[geoff-maddock]

Thanks for the feedback!

[handrews]

No follow-up from OP since 2022, closing.