====== 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. * ''/'' * Liefert mittels GET Informationen zu dem Projekt mit der angegeben ID. * ''/contents'' * Liefert mittels GET eine Liste der Rubriken des Fragenkatalogs * ''/'' * 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 [[:de:results:data-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. * ''/'' * Liefert mittels GET die Datei * ''/databank'' * Liefert per GET den Inhalt der [[:de:create:databank]] * 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 [[:de:results:data-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. --- 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`.