Servicefilter

Mit den von uns zur Verfügung gestellten Servicefiltern können Sie Ihre API-Konsumenten in die Lage versetzen, Antwort-Kollektionen Ihrer API nach bestimmten Kriterien zu filtern. Bei einem Autoren-Service wäre es so beispielsweise möglich, sich alle Autoren ausgeben zu lassen, die mit Vornamen Marcel heißen.

Filtertypen

Wir implementieren eine ganze Reihe an verschiedenen Filtertypen:

Typ Definition
string Ermöglicht das Filtern nach Zeichenketten.
date Ermöglicht das Filtern nach Datumsformaten.
boolean Ermöglicht das Filtern nach true- und false-Werten
numeric Ermöglicht das Filtern nach numerischen Angaben.
range Ermöglicht das Filtern nach Wertebereichen.
exists Ermöglicht das Filtern nach ungleich null-Werten.
order Ermöglicht auf- und absteigende Sortierung nach entsprechenden Kriterien.

Anlegen von Servicefiltern

Wenn Sie einen Servicefilter anlegen möchten, dann spezifizieren Sie den entsprechenden Filtertyp und geben eine Reihe an Servicefeldern (Filtereigenschaften) an, nach denen gefiltert werden soll. Wir geben Ihnen im Folgenden je Filter ein Beispiel zur Erstellung und ein Beispiel zur späteren Verwendung.

Hinweis

Beachten Sie bitte, dass wir die Filtereigenschaften datenbanktechnisch von den jeweiligen Filtern separiert haben. Der einfachheitshalber benutzen wir daher in den folgenden Beispielen die filterProperty-Serialisierungsgruppe und sparen uns damit das Absetzen eines zusätzlichen HTTP-Requests.

Stringfilter

Der Stringfilter ermöglicht das Filtern nach bestimmten Zeichenketten. Die zu filternden Zeichenketten können Sie dabei auf unterschiedliche Art und Weise definieren. Man spricht dabei von sog. Matching Strategies.

Strategie Definition
exact Der Feldwert muss exakt mit der Zeichenkette übereinstimmen. LIKE text
partial Im Feldwert muss die Zeichenkette vorkommen. LIKE %text%
start Der Feldwert startet mit der Zeichenkette. LIKE text%
end Der Feldwert endet mit der Zeichenkette. LIKE %text
word_start Sucht nach Wörtern, die mit der Zeichenkette beginnen. LIKE text% OR LIKE % text%

Setzen Sie bitte noch jeweils ein i vor die jeweilige Strategie, wenn Sie Unempfindlichkeit gegenüber Groß- und Kleinschreibung herstellen möchten. Beachten Sie aber bitte, dass Kollationen für unsere Datenbanktabellen standardmäßig auf utf8mb4_unicode_ci gesetzt sind, welche bereits Unempflichkeit gegenüber Groß- und Kleinschreibung implementieren (_ci = case-insensitive).

Sie senden einen HTTP-POST-Request an den entsprechenden Endpunkt:

curl -X POST "https://localhost/aaas/service/filters?groups[]=filterProperty" ...
{
  "type": "string",
  "service": "/aaas/repository/services/3",
  "properties": [
    {
      "field": "/aaas/service/fields/1",
      "value": "start"
    }
  ]
}

Im obigen Beispiel legen wir einen String-Filter für den entsprechenden Service an und belegen dabei ein Feld mit der start-Match-Strategie.

Beispiel zur Verwendung (Alle Produkte, deren Name mit „kern“ anfangen):

curl -X GET "https://localhost/api/shop/products?name=kern" ...
[
    {
        "id": 6,
        "name": "Kernbohrer",
        "price": "250.00",
        "isInStock": true,
        "createdAt": "2020-08-21T00:00:00+02:00",
        "transportFees": null
    }
]

Datefilter

Der Datefilter erlaubt das Filtern nach Datumsformaten. Wenn Sie ein Servicefeld vom Datentyp date, time oder datetime definiert haben, dann können Sie mithilfe des Datefilters beispielsweise alle Datensätze abfragen, deren Feldwert nach oder vor einem bestimmten Datum liegt. Selbstverständlich können Abfragen auch kombiniert werden.

Beim Abfragen können Sie später folgende HTTP-Query-Parameter setzen:

Parameter Definition
after Feldwert liegt nach dem Datum (Inkl. Datum). ?field[after]=date
before Feldwert liegt vor dem Datum (Inkl. Datum). ?field[before]=date
strictly_after Feldwert liegt nach dem Datum (Exkl. Datum). ?field[strictly_after]=date
strictly_before Feldwert liegt vor dem Datum (Exkl. Datum). ?field[strictly_before]=date

Wenn das Servicefeld null beinhalten kann, dann können Sie entsprechende Datensätze inkludieren oder exkludieren. Setzen Sie dafür beim Anlegen der entsprechenden filterProperty den Wert für value einfach auf einen der folgenden Werte:

Value Definition
exclude_null null-Werte werden exkludiert.
include_null_before Betrachtet Datensätze als Älteste.
include_null_after Betrachtet Datensätze als Jüngste.
include_null_before_and_after null-Werte werden inkludiert.

Sie senden einen HTTP-POST-Request an den entsprechenden Endpunkt:

curl -X POST "https://localhost/aaas/service/filters?groups[]=filterProperty" ...
{
  "type": "date",
  "service": "/aaas/repository/services/3",
  "properties": [
    {
      "field": "/aaas/service/fields/4"
    }
  ]
}

Beispiel zur Verwendung (Alle Produkte, die vor dem 15.08.2020 erstellt wurde):

curl -X GET "https://localhost/api/shop/products?createdAt[before]=2020-08-15" ...
[
    {
        "id": 1,
        "name": "Tieflochbohrer",
        "price": "199.00",
        "isInStock": true,
        "createdAt": "2020-08-11T00:00:00+02:00",
        "transportFees": null
    },
    {
        "id": 2,
        "name": "Spiralbohrer",
        "price": "99.99",
        "isInStock": true,
        "createdAt": "2020-08-07T00:00:00+02:00",
        "transportFees": "10"
    }
]

Beispiel zur Verwendung (Alle Produkte, die nach dem 20.08.2020 und einschließlich vor dem 01.09.2020 erstellt wurde):

curl -X GET "https://localhost/api/shop/products?createdAt[after]=2020-08-20&createdAt[before_strictly]=2020-09-01" ...
[
    {
        "id": 3,
        "name": "Aufbohrer",
        "price": "40.00",
        "isInStock": false,
        "createdAt": "2020-08-20T00:00:00+02:00",
        "transportFees": null
    },
    {
        "id": 5,
        "name": "Festmaß-Aufbohrer",
        "price": "20.00",
        "isInStock": true,
        "createdAt": "2020-09-01T00:00:00+02:00",
        "transportFees": "35"
    },
    {
        "id": 6,
        "name": "Kernbohrer",
        "price": "250.00",
        "isInStock": true,
        "createdAt": "2020-08-21T00:00:00+02:00",
        "transportFees": null
    }
]

Booleanfilter

Der Booleanfilter ermöglicht das Filtern nach true- oder false-Werten. Wenn Sie ein Servicefeld vom Typ boolean definiert haben, dann können Sie später alle Datensätze abfragen, für die der entsprechende Feldwert auf true oder false gesetzt ist:

curl -X POST "https://localhost/aaas/service/filters?groups[]=filterProperty" ...
{
  "type": "boolean",
  "service": "/aaas/repository/services/3",
  "properties": [
    {
      "field": "/aaas/service/fields/3"
    }
  ]
}

Beispiel zur Verwendung (Alle Produkte, für die isInStock auf false gesetzt ist):

curl -X GET "https://localhost/api/shop/products?isInStock=false" ...
[
    {
        "id": 3,
        "name": "Aufbohrer",
        "price": "40.00",
        "isInStock": false,
        "createdAt": "2020-08-20T00:00:00+02:00",
        "transportFees": null
    },
    {
        "id": 4,
        "name": "VHM-Stufenbohrer",
        "price": "20.00",
        "isInStock": false,
        "createdAt": "2020-08-18T00:00:00+02:00",
        "transportFees": null
    }
]

Numericfilter

Der Numericfilter ermöglicht das Filtern nach Werten auf numerischen Feldern:

curl -X POST "https://localhost/aaas/service/filters?groups[]=filterProperty" ...
{
  "type": "numeric",
  "service": "/aaas/repository/services/3",
  "properties": [
    {
      "field": "/aaas/service/fields/2"
    }
  ]
}

Beispiel zur Verwendung (Alle Produkte, deren Produktpreis 20 beträgt):

curl -X GET "https://localhost/api/shop/products?price=20" ...
[
    {
        "id": 4,
        "name": "VHM-Stufenbohrer",
        "price": "20.00",
        "isInStock": false,
        "createdAt": "2020-08-18T00:00:00+02:00",
        "transportFees": null
    },
    {
        "id": 5,
        "name": "Festmaß-Aufbohrer",
        "price": "20.00",
        "isInStock": true,
        "createdAt": "2020-09-01T00:00:00+02:00",
        "transportFees": "35"
    }
]

Rangefilter

Der Rangefilter ermöglicht das Filtern nach Wertebereichen auf numerischen Feldern. Wenn Sie in einem Servicefeld beispielsweise einen Produktpreis persistieren, dann können Sie mithilfe des Rangefilters alle Produkte abfragen, deren Preis in einem bestimmten Bereich liegt.

Bei der späteren Verwendung können Sie einen der folgenden Parameter setzen. Sie können Parameter auch kombinieren.

Parameter Definition
lt Feldwert ist kleiner als Wert. ?field[lt]=value
gt Feldwert ist größer als Wert. ?field[gt]=value
lte Feldwert ist kleiner gleich Wert. ?field[lte]=value
gte Feldwert ist größer gleich Wert. ?field[gte]=value
between Feldwert liegt im Wertebereich. ?field[between]=value1..value2

Sie senden einen HTTP-Post-Request an den entsprechenden Endpunkt:

curl -X POST "https://localhost/aaas/service/filters?groups[]=filterProperty" ...
{
  "type": "range",
  "service": "/aaas/repository/services/3",
  "properties": [
    {
      "field": "/aaas/service/fields/2"
    }
  ]
}

Beispiel zur Verwendung (Alle Produkte mit einer Preisspanne zwischen 150 und 300):

curl -X GET "https://localhost/api/shop/products?price[gt]=150&price[lt]=300" ...
[
    {
        "id": 1,
        "name": "Tieflochbohrer",
        "price": "199.00",
        "isInStock": true,
        "createdAt": "2020-08-11T00:00:00+02:00",
        "transportFees": null
    },
    {
        "id": 6,
        "name": "Kernbohrer",
        "price": "250.00",
        "isInStock": true,
        "createdAt": "2020-08-21T00:00:00+02:00",
        "transportFees": null
    }
]

Existsfilter

Der Existsfilter filtert eine Kollektion nach annullierbaren Feldern. Wenn einer Ihrer Services beispielsweise ein transportFees-Feld (Transportgebühren) implementiert, bei welchem isNullable auf true gesetzt ist, dann können Sie sich später mithilfe des Existsfilter alle Produkte ausgeben lassen, bei denen das entsprechende Feld auf ungleich null gesetzt ist.

Die Syntax bei der späteren Verwendung unterscheidet sich ein wenig von den vorangegangen Beispielen:

Parameter Definition
exists Sie übergeben noch den Feldnamen: ?exists[field]=<true|false|1|0>

Sie senden einen HTTP-Post-Request an den entsprechenden Endpunkt:

curl -X POST "https://localhost/aaas/service/filters?groups[]=filterProperty" ...
{
  "type": "exists",
  "service": "/aaas/repository/services/3",
  "properties": [
    {
      "field": "/aaas/service/fields/5"
    }
  ]
}

Beispiel zur Verwendung (Alle Produkte, bei denen transportFees nicht auf null gesetzt ist):

curl -X GET "https://localhost/api/shop/products?exists[transportFees]=true" ...
[
    {
        "id": 2,
        "name": "Spiralbohrer",
        "price": "99.99",
        "isInStock": true,
        "createdAt": "2020-08-07T00:00:00+02:00",
        "transportFees": "10"
    },
    {
        "id": 5,
        "name": "Festmaß-Aufbohrer",
        "price": "20.00",
        "isInStock": true,
        "createdAt": "2020-09-01T00:00:00+02:00",
        "transportFees": "35"
    }
]

Orderfilter

Der Orderfilter ermöglicht das feldbasierte auf- und absteigende Sortieren Ihrer API-Kollektionen. Bei der späteren Verwendung müssen Sie, wenn Sie keinen Standard definiert haben, die Sortierreihenfolge angeben:

Parameter Definition
asc Sortiert aufsteigend. ?order[field]=asc
desc Sortiert absteigend. ?order[field]=desc

Sie können auch eine Standard-Sortierreihenfolge festlegen, indem Sie als Wert für value entweder ASC oder DESC festlegen:

curl -X POST "https://localhost/aaas/service/filters?groups[]=filterProperty" ...
{
  "type": "order",
  "service": "/aaas/repository/services/3",
  "properties": [
    {
      "field": "/aaas/service/fields/1",
      "value": "ASC"
    }
  ]
}

Beachten Sie bitte, dass wir im Request oben value auf ASC gesetzt haben. ?order[field] sortiert später also automatisch aufsteigend und erwartet dementsprechend keinen Wert für den Parameter.

Beispiel zur Verwendung (Kollektion aufsteigend nach name sortieren):

curl -X GET "https://localhost/api/shop/products?order[name]" ...
[
    {
        "id": 3,
        "name": "Aufbohrer",
        "price": "40.00",
        "isInStock": false,
        "createdAt": "2020-08-20T00:00:00+02:00",
        "transportFees": null
    },
    {
        "id": 5,
        "name": "Festmaß-Aufbohrer",
        "price": "20.00",
        "isInStock": true,
        "createdAt": "2020-09-01T00:00:00+02:00",
        "transportFees": "35"
    },
    {
        "id": 6,
        "name": "Kernbohrer",
        "price": "250.00",
        "isInStock": true,
        "createdAt": "2020-08-21T00:00:00+02:00",
        "transportFees": null
    },
    {
        "id": 2,
        "name": "Spiralbohrer",
        "price": "99.99",
        "isInStock": true,
        "createdAt": "2020-08-07T00:00:00+02:00",
        "transportFees": "10"
    },
    {
        "id": 1,
        "name": "Tieflochbohrer",
        "price": "199.00",
        "isInStock": true,
        "createdAt": "2020-08-11T00:00:00+02:00",
        "transportFees": null
    },
    {
        "id": 4,
        "name": "VHM-Stufenbohrer",
        "price": "20.00",
        "isInStock": false,
        "createdAt": "2020-08-18T00:00:00+02:00",
        "transportFees": null
    }
]

Servicefilter bearbeiten

Sie senden einen HTTP-Put-Request an den entsprechenden Endpunkt und editieren die zu bearbeitenden Felder:

curl -X PUT "https://localhost/aaas/service/filters/1" ...
{
  "type": "order"
}
{
    "id": 1,
    "type": "order",
    "service": "/aaas/repository/services/3",
    "properties": [
        "/aaas/service/filter/properties/1"
    ]
}

Im Beispiel oben ändern wir den Filtertyp auf order.

Servicefilter löschen

Sie senden einen HTTP-Delete-Request an den entsprechenden Endpunkt:

curl -X DELETE "https://localhost/aaas/service/filters/1" ...

Beachten Sie bitte, dass zugehörige Filtereigenschaften ebenfalls gelöscht werden.

Servicefilter anzeigen

Wenn Sie sich alle Filter anzeigen lassen möchten, die zu einem bestimmten Service gehören, dann können Sie einen entsprechenden HTTP-Query-Parameter verwenden:

curl -X GET "https://localhost/aaas/service/filters?service=3" ...
[
    {
        "id": 1,
        "type": "string",
        "service": "/aaas/repository/services/3",
        "properties": [
            "/aaas/service/filter/properties/1"
        ]
    },
    {
        "id": 2,
        "type": "date",
        "service": "/aaas/repository/services/3",
        "properties": [
            "/aaas/service/filter/properties/2"
        ]
    },
    {
        "id": 3,
        "type": "boolean",
        "service": "/aaas/repository/services/3",
        "properties": [
            "/aaas/service/filter/properties/3"
        ]
    },
    {
        "id": 4,
        "type": "numeric",
        "service": "/aaas/repository/services/3",
        "properties": [
            "/aaas/service/filter/properties/4"
        ]
    },
    {
        "id": 5,
        "type": "range",
        "service": "/aaas/repository/services/3",
        "properties": [
            "/aaas/service/filter/properties/5"
        ]
    },
    {
        "id": 6,
        "type": "exists",
        "service": "/aaas/repository/services/3",
        "properties": [
            "/aaas/service/filter/properties/6"
        ]
    },
    {
        "id": 7,
        "type": "order",
        "service": "/aaas/repository/services/3",
        "properties": [
            "/aaas/service/filter/properties/7"
        ]
    }
]

Serialisierungsgruppen

Sie finden im Folgenden eine Übersicht der verwendeten Serialisierungsgruppen von Servicefiltern:

Gruppe Definition
service Serialisiert/Deserialisiert service-Attribute
filterProperty Serialisiert/Deserialisiert filterProperty-Attribute

Serialiserung von Services

Sie setzen groups[] auf service:

curl -X GET "https://localhost/aaas/service/filters/1?groups[]=service" ...
{
    "id": 1,
    "type": "string",
    "service": {
        "id": 3,
        "name": "Product",
        "description": null,
        "type": "list",
        "repository": "/aaas/project/repositories/2",
        "fields": [
            "/aaas/service/fields/1",
            "/aaas/service/fields/2",
            "/aaas/service/fields/3",
            "/aaas/service/fields/4",
            "/aaas/service/fields/5"
        ]
    },
    "properties": [
        "/aaas/service/filter/properties/1"
    ]
}

Serialiserung von Filtereigenschaften

Sie setzen groups[] auf filterProperty:

curl -X GET "https://localhost/aaas/service/filters/1?groups[]=filterProperty" ...
{
    "id": 1,
    "type": "string",
    "service": "/aaas/repository/services/3",
    "properties": [
        {
            "id": 1,
            "value": "start",
            "filter": "/aaas/service/filters/1",
            "field": "/aaas/service/fields/1"
        }
    ]
}

Deserialiserung von Filtereigenschaften

Sie setzen groups[] auf filterProperty und senden valide Daten:

curl -X POST "https://localhost/aaas/service/filters/1?groups[]=filterProperty" ...
{
  "type": "string",
  "service": "/aaas/repository/services/3",
  "properties": [
    {
      "field": "/aaas/service/fields/1",
      "value": "partial"
    }
  ]
}
{
    "id": 1,
    "type": "string",
    "service": "/aaas/repository/services/3",
    "properties": [
        {
            "id": 1,
            "value": "start",
            "filter": "/aaas/service/filters/1",
            "field": "/aaas/service/fields/1"
        }
    ]
}