====== 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 [[:de:results:data-api]] verwendet werden.
        * ''/dataset.csv''
          * Wie ''dataset'', liefert den Datensatz aber im CSV-Format für R.


===== Abruf der Projektliste =====

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

<code json>
[
	{
		"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
	}
]
</code>

  * 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.

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

Zur Ausgabe des Datensatzes als JSON siehe [[:de:results:data-api]]