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.

Eine OpenAPI Specification (OAS) zur Entwicklung mittels Swagger finden Sie unter https://www.soscisurvey.de/templates/sosci-survey-api.yaml. Aktivieren Sie beim API-Zugriff die Option Zugriff für Web-Applikationen und tragen Sie in Swagger als „Bearer“ den API-Schlüssel ein.

API Schlüssel erstellen

Für den Zugriff auf die REST-API ist ein API-Schlüssel erforderlich. Dieser wird im Benutzerkonto unter API-Zugriff erstellt.

Hinweis: Ein API-Schlüssel gilt jeweils für das Benutzerkonto auf dem Server, auf welchem es angelegt wurde. Wenn Sie einen API-Schlüssel auf www.soscisurvey.de erstellt haben, gilt diese nicht für Projekte auf s2survey.net. Um einen API-Schlüssel auf dem Pro-Server zu erstellen, klicken Sie im Befragungsprojekt auf Spezialfunktionen → API-Zugriff.

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.

Funktionen

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.
  - /uploads
    - Liefert mittels GET eine Liste der von Befragten hochgeladenen Dateien.
    - /<Dateiname>
      - Liefert mittels GET die Datei
  - /databank
    - Liefert per GET den Inhalt der Datenbank für Inhalte
    - Erlaubt per POST das Hinzufügen und Aktualisieren von Einträgen

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 abrufen

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

Dateien herunterladen

Sie könen mittels API und R auch alle von den Befragten hochgeladenen Dateien aus einem Befragungsprojekt herunterladen. Verwenden Sie dafür optional folgendens R Markdown.

Erstellen Sie im Benutzerkonto unter API-Zugriff ein neues API-Token, welches lesenden Zugriff auf `/projects` und `/projects/uploads` hat (`/projects` können Sie weglassen, wenn Sie die Projekt-ID bereits kennen)
Kopieren Sie die „API URL“ und tragen Sie diese in den Setup-Block des R-Scripts ein.
Kopieren Sie den „API Schlüssel“ und tragen Sie auch diese in den Setup-Block ein.
Je nachdem, ob Sie die (numerische) Projekt-ID eintragen oder nicht, wird die Liste der Projekte abgerufen und ausgegeben oder die Dateien werden direkt heruntergeladen.

uploads.rmd

---
title: "Download Uploads"
author: "SoSci Survey"
date: "`r Sys.Date()`"
output: html_document
---
 
## Preparation
 
  * Go to the user account, select **API Access** and create
    a new token that is allowed to read `/projects` and `/projects/uploads`
    (you can skip `/projects` if you already know the project's ID)
  * Copy the "API URL" and paste here the setup script below
  * Copy the "API key" and paste into the script
 
 
```{r setup, include=FALSE}
# R setup block
knitr::opts_chunk$set(echo = TRUE)
 
# Insert the API URL below
api_url <- "INSERT HERE"
 
# Insert the API key below
api_key <- "INSERT HERE"
 
# Insert the project's ID below,
# eventually to be added after running the "projects" block
project_id <- 0
 
if (!require("pacman")) {
    install.packages("pacman")
    library("pacman")
}
p_load("httr2")
```
 
 
## Projects
 
Now, find the project's ID in this list (skip this code block if you already know the project's ID).
 
```{r projects, results='asis'}
if (project_id < 1) {
    req <- request(paste(api_url, "/projects", sep="")) |> req_auth_bearer_token(api_key)
    resp <- req |> req_perform()
    api_projects <- resp |> resp_body_json()
 
    for (api_project in api_projects) {
        cat(paste("  * ID ", api_project$id, ": ", api_project$title, "\r\n", sep=""))
    }
 
    rm(api_projects, api_project, resp, req)
} else {
    cat("Already set a project ID, skipping project listing retrieval.\r\n")
}
```
 
**Note:** Write the project's ID to `project_id` in the setup block (if not already done).
 
**Note:** Should you see an 401 error, make sure to grant the API key reading access to `/projects`.
 
 
## Download Uploads
 
Download the uploads to ''/uploads''.
 
```{r download, results='asis'}
if (project_id < 1) {
    cat("No project ID set, yet. Stopping processing.\r\n")
} else {
    req <- request(paste(api_url, "/projects/", project_id, "/uploads", sep="")) |> req_auth_bearer_token(api_key)
    resp <- req |> req_perform()
    api_uploads <- resp |> resp_body_json()
 
    dir.create("uploads", showWarnings = FALSE)
 
    for (upload_filename in api_uploads$files) {
        # Skip download if the file already exists
        if (file.exists(paste("uploads", upload_filename, sep="/"))) {
            cat(paste("  * ", upload_filename, " (skipped, already present)\r\n", sep=""))
        } else {
            cat(paste("  * ", upload_filename, "\r\n", sep=""))
            # Download the file and store to /uploads
            req_file <- request(
                    paste(api_url, "/projects/", project_id, "/uploads/", upload_filename, sep="")
                ) |> req_auth_bearer_token(api_key)
            req_file |>
                req_perform(path = paste("uploads", upload_filename, sep="/"))
        }
    }
    rm(upload_filename, api_uploads, resp, req, req_file)
}
 
rm(api_key, api_url, project_id)
```
 
**Note:** Should you see an 401 error, make sure to grant the API key reading access to `/projects/uploads`.