API
Über die primedocs Web API lassen sich Informationen abfragen und Dokumentgenerierungen auslösen. Folgende Schnittstellen stehen zur Verfügung:
- Admin API: Verwaltung von primedocs-Ressourcen.
- Connect API: serverseitige Dokumentgenerierung anstossen.
- Connect Session API: sitzungsbasierte Dokumentgenerierung.
Informationen zur Anmeldung an der API finden Sie unter Authentifizierung.
Basis-URL und Routing
Alle Endpunkte sind versioniert und liegen unter dem Routen-Präfix /api/v3/{datasourceId}/…. In einer Standard-Installation ist die Web API zusätzlich unter dem Host-Pfad /webapi eingebunden, sodass sich die vollständige URL wie folgt zusammensetzt:
https://{instanz}/webapi/api/v3/{datasourceId}/…
Die {datasourceId} identifiziert die anzusprechende Datasource.
Fehlerbehandlung
Erfolgreiche Aufrufe antworten mit 2xx. Im Fehlerfall werden die folgenden HTTP-Statuscodes verwendet:
| Status | Bedeutung |
|---|---|
400 Bad Request | Ungültige Eingabe, z.B. fehlerhaftes Connect-XML oder ungültige Parameter. |
401 Unauthorized | Kein oder ungültiges Access Token. |
403 Forbidden | Das Token besitzt nicht die nötigen Rechte (Scope/Rolle) für die Operation. |
404 Not Found | Die Ressource wurde nicht gefunden, z.B. eine unbekannte datasourceId oder eine abgelaufene Session. |
500 Internal Server Error | Unerwarteter Fehler bei der Verarbeitung. |
Unbehandelte Fehler werden als JSON im folgenden Format zurückgegeben:
{
"message": "Beschreibung des Fehlers",
"isError": true,
"detail": "Zusätzliche Details (nur in Debug-Builds inkl. Stacktrace)"
}
Die Web API verwendet grundsätzlich kein RFC 7807 (ProblemDetails). Ausnahmen sind einzelne Bereiche der Admin API, darunter der Paket-Export und -Import und die Themes der Organisationseinheiten: Sie antworten bei fachlichen Fehlern mit ProblemDetails und einem maschinenlesbaren code. Einzelne Endpunkte der Connect API können im Fehlerfall zusätzlich einen fachlichen Bericht (ConnectResultReport, siehe Connect API) liefern.