Filter Endpoints

Filter Endpoints provide a way to directly access and adjust specific Filter parameters. This makes it possible to indicate what Filter parameters can or should be changed when someone uses the Filter, specifically when using the API. Even when the Filter is complex and could involve deep relational filtering, endpoints expose certain parameters at the top level.

A Filter Endpoint has three components: an endpoint configuration form, a dictionary with key-values to set the parameters, and the stored Filter (ID) itself.  

Endpoint Configuration    

The form to configure an endpoint should be provided in YAML/JSON format and is to be stored in the 'description' field when saving the Filter.

An endpoint configures parameters defined by an object:
{"key": {"description": "What does it do?", "path": "form/..."}}

The key should be a short variable-like name, and the definition further defines what it accesses:

descriptionA description on what Filter element the parameter accesses and what it would accomplish. This description is included in the API's OpenAPI description, and will also help large language models (ML/AI) access the parameter.
pathDefine the path to the element in the Filter form. The targeted element can be an array to be able to add multiple values, or a specific position. The path goes straight through the JSON, where any key or index is followed by an /.

The following example configures three directly accessible parameters:

Selects all letters sent, in a date range. by persons, filtered by family name.

---
family_name:
  description: Family name to select Persons who sent Letters
  path: form/filter_2/object_definitions/10/0/value
date_start:
  description: The earliest date when a Letter is sent
  path: form/filter_1/object_subs/1/object_sub_dates/0/object_sub_date_from
date_end:
  description: The latest date when a Letter is sent
  path: form/filter_1/object_subs/1/object_sub_dates/0/object_sub_date_to

Endpoint Dictionary  

A dictionary accesses the available parameters and provides all relevant values to be filtered on. A Filter ID with the key filter_id is required. For example, the endpoint above can be realised by the following dictionary in JSON format:

{"filter_id": 19, "family_name": "Štúr", "date_start": "1850-02-01", "date_end": "1860"}

Filter Form  

The above configuration is based on the following form, stored with Filter ID 19. Filter forms can be acquired by selecting the 'Advanced' tab when clicking 'save'.

{
    "form": {
        "filter_1": {
            "type_id": 1,
            "source": null,
            "options": {
                "operator": "object_or_sub_or",
                "operator_extra": "1",
                "exclude": ""
            },
            "object_subs": {
                "1": {
                    "object_sub_dates": [
                        {
                            "object_sub_date_type": "range",
                            "object_sub_date_from": "1810",
                            "object_sub_date_to": "1815",
                            "object_sub_date_chronology": ""
                        }
                    ]
                }
            }
        },
        "filter_2": {
            "type_id": 4,
            "source": {
                "filter_code": "filter_1",
                "filter_type_id": 1,
                "filter_beacon": "",
                "type_id": 1,
                "object_description_id": 161,
                "object_sub_details_id": 0,
                "object_sub_description_id": 0,
                "direction": "out"
            },
            "options": {
                "operator": "object_or_sub_or",
                "operator_extra": "1",
                "exclude": ""
            },
            "object_definitions": {
                "10": [
                    {
                        "equality": "*",
                        "value": "grimm"
                    }
                ]
            }
        }
    }
}