API-Übersicht¶

Die TBA3-API stellt Evaluationsdaten auf drei Ebenen bereit: Lerngruppe, Schule und Land. Jede Ebene bietet drei Datentypen an.

API-Spezifikation

Die vollständige Dokumentation ist unter Swagger UI einsehbar.

Endpunkte¶

Endpunkt	Beschreibung
`GET /groups/{id}/competence-levels`	Kompetenzstufenverteilung einer Lerngruppe
`GET /groups/{id}/items`	Aufgaben- und Item-Daten einer Lerngruppe
`GET /groups/{id}/aggregations`	Aggregierte Kennwerte einer Lerngruppe
`GET /schools/{id}/competence-levels`	Kompetenzstufenverteilung einer Schule
`GET /schools/{id}/items`	Aufgaben- und Item-Daten einer Schule
`GET /schools/{id}/aggregations`	Aggregierte Kennwerte einer Schule
`GET /states/{id}/competence-levels`	Kompetenzstufenverteilung auf Landesebene
`GET /states/{id}/items`	Aufgaben- und Item-Daten auf Landesebene
`GET /states/{id}/aggregations`	Aggregierte Kennwerte auf Landesebene

Query-Parameter¶

Alle Endpunkte unterstützen optionale Query-Parameter:

Parameter	Beschreibung	Beispiel
`type`	Granularität der Daten	`?type=students` -- eine Value-Group pro Schüler
`comparison`	Filter für Vergleichsgruppen	`?comparison=Landesmittelwert`
`aggregation`	Filter für Aggregationstyp (nur `/aggregations`)	`?aggregation=competence`

`type`-Werte je Ebene¶

Ebene	`type`-Wert	Ergebnis
`/groups`	`students`	Eine Value-Group pro Schüler
`/schools`	`students`	Aggregiert pro Schüler
`/states`	`district`	Eine Value-Group pro Schulamtsbezirk
`/states`	`schools`	Eine Value-Group pro Schule

`aggregation`-Werte¶

Wert	Beschreibung
`competence`	Lösungshäufigkeiten nach Kompetenzbereich
`exercise`	Lösungshäufigkeiten nach Aufgabe
`competenceLevel`	Lösungshäufigkeiten nach Kompetenzstufe (I-V)
`domain`	Lösungshäufigkeiten pro Domäne (bei `type=students`)

Value-Group-Konzept¶

Alle API-Responses sind als Array von Value-Groups strukturiert. Eine Value-Group kombiniert Metadaten mit den eigentlichen Daten.

[
  {
    "id": "group-1",
    "name": "Klasse 8.3",
    "domain": { "name": "Lesen" },
    "subject": { "name": "Deutsch" },
    "competenceLevels": [ ... ]
  },
  {
    "id": "comparison-school",
    "name": "Schule",
    "competenceLevels": [ ... ]
  }
]

Die erste Value-Group enthält typischerweise die Hauptdaten (z.B. der eigenen Klasse), die weiteren Value-Groups enthalten Vergleichsdaten (z.B. Schul- oder Landesdurchschnitt).

Vergleichsdaten¶

Vergleichsdaten werden als separate Value-Groups im selben Response oder als comparison-Array innerhalb einzelner Datenpunkte geliefert. Sie werden durch ihren name identifiziert (z.B. "Schule", "Landesmittelwert").

Kovariaten¶

Demografische Merkmale der Schüler werden als Kovariaten transportiert:

Kovariate	API-Bezeichner	Mögliche Werte
Geschlecht	`gender`	`male`, `female`, `diverse`
Sprache zu Hause	`languageAtHome`	`german`, `other`
Sozioökonomischer Status	`ses`	`A`, `B`, `C`, `D`, `E`