Core - Filters
==============
.. Last update: 16/08/2021

To make a reservation the User Agent must ask the user some standard data (pick-up and drop-off
points and date/time) and some ad-hoc filters, that can be retrieved via this API endpoint.

The base url for the APIs in this page is at::

  /api/mobile/

A JSON file with OpenAPI data about all core-related mobile APIs can be downloaded :download:`here </openapi/srv-core/api-src-WebMobile.json>`.

Get the list of filters
-----------------------

.. openapi:: /openapi/srv-core/api-src-WebMobile.json
   :paths:
     /v1/transportation-requests/filters

The resulting object is like this::

  [
    {
      "CreatedDate": "2019-05-28T11:41:26Z",                                                           // DateTime
      "LastUpdated": "2020-09-01T08:33:56Z",                                                           // DateTime
      "ValueType": 4,                                                                                  // Int
      "Key": "vg-category",                                                                            // String
      "Labels": "{\"en\":\"Category\"}",                                                               // JSON Dictionary
      "ValidValues": "["9060503a-5ba6-42b4-a01e-cbce1cb98c7e", ... ]",                                 // String Array, nullable
      "ValidValuesLabels": "{\"9060503a-5ba6-42b4-a01e-cbce1cb98c7e\":{\"en\":\"City Car\"}, ...}",    // JSON Dictionary (nullable)
      "IsRequired": true,                                                                              // Boolean
      "ID": 1                                                                                          // Int
    }
  ]

Implementing User Agent should parse and store locally the filters required for compiling the
Transportation Requests.

The ``Labels`` property contains a JSON dictionary that must be separately parsed. In the
dictionary there is the proper translation, for available IETF language tag, of the meaning
of this filter.

The value of the ``Key`` property can be one of the value described in :ref:`details-ma-filters`.

The ``ValidValues`` field is a stringified array whose value, when present depending on the value of the
``ValueType`` field (see below), may vary depending on the context of the specific filter
(i.e. it may be a number array, Guid array, string array...).

In the ``ValidValuesLabels`` property there is a context-dependent JSON dictionary that must
be separately parsed by the User Agent. In the dictionary, for each valid value, there is the
proper translation, for available IETF language tags, of the meaning of such value.

If the filter has the ``IsRequired`` property set to ``true``, the User Agent must specify a
value for the filter when compiling a Transportation Request, otherwise the submission will
fail. Such value can be decided autonomously by the User Agent or can be asked to the user.

The User Agent can also hardwire some filter keys and present an autonomously defined UI,
without making any use of the ``Labels`` or ``ValidValuesLabels`` properties.

Value types can be one of the :ref:`enum-additionalvaluetypes` enumeration,
with the following implications:

=================== =============
Value               Implications
=================== =============
Number              In the ``ValidValues`` there can be a JSON array of two items, the first
                    being the lower bound and the second being the upper bound of the allowed
                    range.
                    A value of null or undefined lets the end unbounded.
                    No ``ValidValuesLabels`` are to be expected.
Boolean             No ``ValidValues`` are to be expected, but there can be ``ValidValuesLabels``.
String              No ``ValidValues`` are to be expected, nor ``ValidValuesLabels``.
Enumeration         Both ``ValidValues`` and ``ValidValuesLabels`` are to be expected, as in the
                    example data above.
                    The User Agent must specify exactly one of the valid
                    values in the JSON array contained in ``ValidValues`` as the filter value
                    when compiling a Transportation Request.
Multi-enumeration   Both ``ValidValues`` and ``ValidValuesLabels`` are to be expected, as in
                    the example data above.
                    The User Agent must specify at least one, and
                    possibly more, of the valid values in the JSON array contained in
                    ``ValidValues`` as the filter value when compiling a Transportation
                    Request.
                    The filter value must be a string containing a JSON array of
                    the selected values.
=================== =============