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.
    • /contents
      • Liefert mittels GET eine Liste der Rubriken des Fragenkatalogs
      • /<Rubrik-Kennung>
        • Liefert mittels GET eine Liste der Fragen und Texte in der Rubrik
    • /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.

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.

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/130/dataset?changedMin=2025-02-20T16:32:00

Zur Ausgabe des Datensatzes als JSON siehe Datenabruf via API