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"
}
]
}