Inhalt
Query Parameter
Um die Antwort einer API-Anfrage zu filtern, etwas anzufügen oder zu generell zu verändern, kann man an die Index- und Show-Routen gewisse Query Parameter anhängen.
Query Parameter sind Key-Value Paare am Ende der URL, getrennt mit einem & und beginnend mit einem ?.
Beispielsweise möchte man sich alle Endnoten der 5b, die die ID 3 hat, sortiert nach Datum aufsteigend geben lassen, so fügt man die Query Parameter filter[group]=3 und sort=given_at. Die gesamte URL sieht dann so aus:
https://beste.schule/api/finalgrades?filter[group]=3&sort=given_atWelche Query Parameter es gibt, unterscheidet sich je nach Entität, jedoch welche es immer gibt, und wie sie funktionieren wird im Folgenden erklärt.
Filter (filter)
Ein Filter sorgt dafür, dass sich die Menge der Ergebnisse verkleinert, basierend auf dem Wert, nach welchem gefiltert wird.
Generell folgen die Filter Parameter immer dem gleichen Schema.
filter[<schlüssel>]=<wert>Dabei ist <schlüssel> der Typ des Filters, also nach welcher Entität oder welchem Feld im Entitätenobjekt gefiltert wird. Und <wert> ist der konkrete Wert, welche alle gesuchten Entitäten haben müssen. Es können auch mehrere Werte als Komma-getrennte Liste angegeben werden.
Es gibt einige globale Filter, welche auf fast alle Entitäten anwendbar sind.
| Schlüssel | Wertebereich | Beispiel |
student | ID(s) von Schüler*innen | Noten von bestimmten Schüler*innen, Klassenbuch eines*einer Schülers*ins |
guardian | ID(s) von Eltern | Kinder (Schüler*innen) von bestimmten Eltern |
group | ID(s) von Klassen | Schüler*innen, die in bestimmten Klassen sind |
subject | ID(s) von Fächern | Endnoten in einem bestimmen Fach |
interval | ID(s) von Halbjahr | Abwesenheitsmeldungen in einem bestimmten Halbjahr |
year | ID(s) von Schuljahren | Halbjahre eines Jahres |
teacher | ID(s) von Lehrer*innen | Noten die ein*e bestimmte*r Lehrer*in erstellt hat |
Anfügen von Relations (include)
Eine Relation ist eine andere Entitätenmenge, die in Beziehung mit der angefragten Entitätenmenge steht. So steht zum Beispiel eine Endnote mit genau einem*einer Schüler*in in Beziehung.
Mit dem include Parameter lassen sich solche Beziehungen mit in die Antwort inkludieren. Das ist hilfreich um die Anzahl gestellter Anfragen zu minimieren.
Möchte man zum Beispiel das Schüler*innenobjekt und das Halbjahresobjekt mit an allen Endnotenobjekten haben so stellt man eine GET Anfrage an finalgrades?include=student,interval. Die Antwort sind dann ungefähr so aus:
[
{
"student": {...},
"interval": {...},
...
},
...
]
Kapitel
