REST API

SoSci Survey bietet für verschiedene Funktionen mittels API Möglichkeiten zur Automatisierung.

Ab Version 3.6.12 werden diese Funktionen über eine einheitliche REST-API verfügbar gemacht. Für den Zugriff auf die REST-API ist ein API-Schlüssel erforderlich. Dieser wird im Benutzerkonto unter API-Zugriff erstellt.

Der API-Schlüssel ist an ein Benutzerkonto gebunden und hat grundsätzlich nur die Berechtigungen, welche auch das Benutzerkonto hat. Darüber hinaus kann beim Erstellen des API-Schlüssels eingestellt werden, für welche Funktionen dieser genutzt werden kann.

Wichtig: Derzeit kann noch kein IP-Filter für die Nutzung des API-Schlüssels konfiguriert werden. Schützen Sie den API-Schlüssel sehr gut, weil Dritte damit Zugriff auf Ihr Benutzerkonto und Ihre Befragungsprojekte erlangen können.

Wenn Sie den API-Schlüssel unter API-Zugriff anklicken, wird Ihnen eine API-URL und ein HTTP Header angezeigt. Der Header enthält den API-Schlüssel. Diese Authorization Header muss in der Anfrage übermittelt werden, um Zugriff zu erhalten.

Die folgenden Ressourcen (Endpoints) sind unterhalb der API-URL derzeit verfügbar, alle Ressourcen liefern die Daten in JSON. Der HTTP Statuscode gibt an, ob die Abfrage erfolgreich war.

/projects
- Liefert mittels GET eine Liste aller Befragungsprojekte im Benutzerkonto inkl. Datenbank-IDs.
- /<ProjektID>
  - Liefert mittels GET Informationen zu dem Projekt mit der angegeben ID.
    - /dataset
      - Liefert mittels GET die Daten entsprechend den Auswahlkriterien für gültige Fälle, wie sie im Befragungsprojekt eingestellt sind.
      - Für den Abruf ausgewählter Fälle können die GET-Parameter entsprechend Datenabruf via API verwendet werden.
    - /dataset.csv
      - Wie dataset, liefert den Datensatz aber im CSV-Format für R.

Abruf der Projektliste

https://www.soscisurvey.de/admin/api.php?v1/projects

[
	{
		"id": 104,
		"folder": "alpha",
		"title": "Projekt Alpha",
		"server": "soscisurvey.de",
		"active": true,
		"accessible": true
	},
	{
		"id": 17,
		"folder": "beta",
		"title": "Projekt Beta",
		"server": "soscisurvey.de",
		"active": true,
		"accessible": true
	},
	{
		"id": 103,
		"folder": "gamma",
		"title": "Projekt Gamma",
		"server": "soscisurvey.de",
		"active": true,
		"accessible": true
	}
]

Die id ist die Datenbank-ID, welche für den Zugriff auf das Befragungsprojekt erforderlich ist.
Der Eintrag active gibt an, ob das Befragungsprojekt noch aktiv ist oder bereits archiviert wurde.
Der Eintrag accessible gibt an, ob das Befragungsprojekt über diese API-URL erreichbar ist oder ob es sich auf einem anderen Befragungsserver befindet, und ggf. über die API-URL dieses Befragungsservers angesprochen werden muss.

Daten anrufen

Der folgende Aufruf würde aus dem Projekt mit der ID 130 alle Fälle abrufen, deren Daten nach dem 20.02.2025, 16:32 Uhr geändert wurden.

https://www.soscisurvey.de/admin/api.php?v1/projects/103/dataset?changedMin=2025-02-20T16:32:00

Zur Ausgabe des Datensatzes als JSON siehe Datenabruf via API