Cloned from launchpad blueprint https://blueprints.launchpad.net/keystone/+spec/dynamic-filter-discovery-on-rest-api.

Description:

Problem
=====

Keystone V3 specification supports filter on list APIs and the supported filters are defined in specification docs. This approach of static filter discovery is not sufficient to support following use cases

1. Clients (e.g. Horizon) wants to dynamically discover filters and render them in their system. This way they don't have to change their implementation (code) each time when a new filter is added or removed from the API.
 
2. There is no way for a clients (e.g. Horizon) to validate Input value for filter by end users.

3. This approach is not  convenient for extension providers who want to have additional filters on extended APIs.

Proposal
=====

Keystone list APIs has to support additional path parameter called "filters", request with this parameter should return JSON response with list of supported filters in certain format.  This way clients can conveniently discover all the supported filters on an API, render them in their system (or web page) and they can validate the user input values for filter based on the response.

Following is data structure for the filters response.

{
  "filters": [
    {
      "name": "--filter-name--",
      "type": "pick-list",
      "isExclusive": "true",
      "possibleValues": ["value1","value2"],
      "description": "--filter description--"
    },
    {
      "name": "--filter-name--",
      "type": "integer",
      "isExclusive": "false",
      "description": "--filter description--"
    },
    {
      "name": "--filter-name--",
      "type": "String",
      "isExclusive": "false",
      "description": "--filter description--"
    },
    {
      "name": "--filter-name--",
      "type": "boolean",
      "isExclusive": "false",
      "description": "--filter description--"
    }
  ]
}

Examples
======

API : GET /endpoints/filters

Response
{
  "filters": [
    {
      "name": "interface",
      "type": "pick-list",
      "isExclusive": "false",
      "possibleValues": ["public","internal","restricted"],
      "description": "optional filter"
    },
    {
      "name": "service_id",
      "type": "integer",
      "isExclusive": "false",
      "description": "optional filter"
    },
    {
      "name": "region",
      "type": "pick-list",
      "isExclusive": "false",
      "possibleValues": ["region-a-geo1","region-a-geo2","region-a-geo2"],
      "description": "optional filter"
    }
  ]
}

API: GET /users/filters

Response
{
  "filters": [
    {
      "name": "enabled",
      "type": "boolean",
      "isExclusive": "false",
      "description": "optional filter"
    },
    {
      "name": "domain_name",
      "type": "String",
      "isExclusive": "false",
      "description": "optional filter"
    }
  ]
}

Specification URL (additional information):

None