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. Fehlerhafte Aufrufe beantwortet die Web API mit einem Problem-Dokument nach RFC 7807 im Medientyp application/problem+json. Das gilt für Admin API, Connect API und Connect Session API und auch für Fehler, die vor dem eigentlichen Endpunkt entstehen, etwa bei der Authentifizierung oder bei einer unbekannten datasourceId.

Beispiel für ein Connect ohne Author-Element an POST …/Connect/Document:

{
  "type": "about:blank",
  "title": "Bad request",
  "status": 400,
  "detail": "Invalid connect: No Author is set. Add an Author element with a Profile Id to the connect.",
  "instance": "/api/v3/{datasourceId}/Connect/Document",
  "code": "Connect.Invalid",
  "correlationId": "0HN7ABCDEF:00000001"
}

Feld	Beschreibung
type	Immer about:blank.
title	Kurze Zusammenfassung zum Status, z.B. Bad request.
status	HTTP-Statuscode der Antwort.
detail	Beschreibung des Fehlers, bei Eingabe- und Ausführungsfehlern mit dem Grund und, wo möglich, der nötigen Korrektur.
instance	Aufgerufener Pfad. Fehlt, wenn der Pfad vertrauliche Werte enthalten könnte.
code	Stabiler, maschinenlesbarer Fehlercode, siehe Fehlercodes.
correlationId	Kennung des Aufrufs. Derselbe Wert steht im Antwort-Header X-Correlation-ID und im Server-Log.
errors (optional)	Weitere Meldungen, die detail nicht bereits enthält.
helpLink (optional)	Verweis auf weiterführende Dokumentation, sofern vorhanden.

Weitere Felder sind möglich, etwa unavailableConnectedServiceKeys bei Connect.ConnectedServicesNotReady (siehe Connect Session API).

Statuscodes

Status	Bedeutung
400 Bad Request	Ungültige Eingabe, z.B. fehlerhaftes oder unvollständiges Connect-XML, ein Connect ohne Author, ungültige Sprachcodes oder Parameter, die der Endpunkt ausdrücklich prüft (InvalidQuery, InvalidBody). Der Aufrufer kann den Fehler selbst beheben. Nicht lesbare Query- oder Routenwerte führen nicht überall zu 400.
401 Unauthorized	Kein oder ungültiges Access Token, siehe Authentifizierungsfehler.
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, ein unbekannter Benutzer oder eine abgelaufene Session.
409 Conflict	Die Änderung widerspricht dem aktuellen Zustand, z.B. bei einer gleichzeitigen Änderung.
413 Payload Too Large	Der Request-Body überschreitet die zulässige Grösse.
422 Unprocessable Entity	Die Anfrage ist gültig, konnte aber nicht ausgeführt werden, z.B. wegen ungültiger Formularwerte, fehlerhafter Inhalte in Data, einer nicht unterstützten Dokumentsprache, eines fehlenden MIP-Zugriffs oder einer Connect-Policy.
500 Internal Server Error	Unerwarteter technischer Fehler. Die Antwort enthält nur eine allgemeine Meldung und die correlationId.
503 Service Unavailable	Ein benötigter Dienst ist nicht erreichbar, z.B. der Identity Server bei der Prüfung des Tokens (AuthenticationUnavailable), oder der Server ist für die Anfrage nicht eingerichtet (Admin.ImportExport.NotConfigured). Bei AuthenticationUnavailable den Aufruf später wiederholen.

Fehler auswerten

• Status und code auswerten. code ist Teil des Vertrags und ändert sich nicht ohne Ankündigung. Verzweigungen in einer Integration darauf abstützen, nicht auf title oder detail.
• detail ist immer englisch und wird weder nach der Sprache des Aufrufers noch nach der des Benutzers übersetzt. Der Text richtet sich an das integrierende System und seine Entwickler. Für eine Anzeige an Endbenutzer gezielt einsetzen oder durch eigene Texte ersetzen.
• correlationId für den Support angeben. Interne Fehlerdetails wie Exception-Meldungen oder Stacktraces gibt die API nicht heraus. Sie stehen unter derselben Kennung im Server-Log.

Fehlercodes

Allgemeine Codes sagen nicht mehr als der Status und stehen, wenn kein spezifischer Code zutrifft:

Code	Bedeutung
BadRequest	Ungültige Anfrage
InvalidBody	Der Request-Body konnte nicht gelesen werden
InvalidQuery	Ein Query- oder Routenparameter fehlt oder ist ungültig
NotFound	Ressource nicht gefunden
Unauthorized	Kein oder ungültiges Access Token
AuthenticationUnavailable	Das Token konnte nicht geprüft werden, weil der Identity Server nicht antwortet
Forbidden	Fehlende Berechtigung
ConcurrentModification	Die Änderung ist mit einer gleichzeitigen Änderung kollidiert (nur Admin API)
TechnicalError	Unerwarteter technischer Fehler

Connect API und Connect Session API:

Code	Bedeutung
Connect.Empty	Kein Connect im Request
Connect.Invalid	Das Connect ist ungültig, etwa nicht wohlgeformt oder ohne Author
Connect.NotSupported	Das Connect verlangt etwas, das der Endpunkt nicht unterstützt, z.B. lokale Dateipfade oder Desktop-Befehle
Connect.MultipartDocumentMissing	Bei /Update fehlt im Multipart-Request der Teil document
Connect.InvalidConversion	Ungültiger Wert für conversion
Connect.UserNotResolved	Die Benutzerabfrage ergibt keinen oder mehrere Benutzer
Connect.ExecutionFailed	Das Connect konnte nicht ausgeführt werden. detail und errors nennen die Gründe
Connect.SessionNotFound	Die Session existiert nicht oder ist abgelaufen
Connect.SessionResultNotFound	Für die Ausführung ist kein Ergebnis gespeichert
Connect.InvalidSessionTemplate	Die Connect Session Template ist ungültig oder nicht angegeben
Connect.ConnectedServicesNotReady	Der Benutzer muss sich zuerst bei Connected Services anmelden

Admin API:

Code	Bedeutung
Admin.RequiresRole	Dem Aufrufer fehlt die nötige Administrationsrolle
Admin.RequiresAdminApiClient	Der Endpunkt steht nur Admin-API-Clients und im Web-Admin angemeldeten Administratoren offen, nicht Connect- oder MCP-Tokens
Admin.SecretsRequireInteractiveUser	Die Operation zeigt oder ersetzt Geheimnisse und steht nur einem im Web-Admin angemeldeten Administrator offen
Admin.InvalidRowVersion	rowVersion fehlt oder ist kein vom Server ausgegebener Wert
Admin.Role.Unknown	Die Route nennt keine der festen Administrationsrollen
Admin.Role.UnsupportedPrincipalType	Rollen lassen sich nur Benutzern, Verzeichnisgruppen und App-Gruppen zuweisen
Admin.Role.PrincipalNotFound	Das Konto existiert in dieser Datasource nicht
Admin.Role.NotMaterialized	Die Rollendefinition existiert in dieser Datasource nicht
Admin.Role.DefinitionConflict	Für die Rolle bestehen mehrere Definitionen
Admin.Role.MembershipConflict	Die Rollenmitgliedschaft wurde gleichzeitig geändert
Admin.DynamicGroup.ConfigurationMissing	Die dynamische Gruppe hat keine gespeicherte Konfiguration
Admin.DynamicGroup.EvaluationFailed	Die gespeicherte Konfiguration der dynamischen Gruppe lässt sich nicht auswerten
Admin.OrganizationUnit.InvalidTheme	Das Thema der Organisationseinheit ist ungültig, z.B. fehlerhaftes XML
Admin.OrganizationUnit.ThemeRequiresDedicatedEndpoint	Themenfelder werden über den Themen-Endpunkt geschrieben, nicht über die Aktualisierung der Organisationseinheit
Admin.ImportExport.NotConfigured	Auf dem Server ist kein Pfad für Export und Import konfiguriert
Admin.ImportExport.InvalidSelection	Die gewählten Objekte, Abhängigkeiten oder Katalogknoten sind unbekannt oder leer
Admin.ImportExport.MissingPackageFile	Die Paketdatei fehlt
Admin.ImportExport.UnsupportedPackageFormat	Das Paketformat wird nicht unterstützt
Admin.ImportExport.PackageTooLarge	Das Paket ist zu gross
Admin.ImportExport.LegacyFile	Der Export wurde mit der früheren DataSourceAdminApp erstellt, die Datei liegt dort
Admin.ImportExport.ExportNotFinished	Der Export ist noch nicht abgeschlossen
Admin.ImportExport.FileNoLongerAvailable	Die Paketdatei wurde entfernt, ein neuer Export ist nötig
Admin.ImportExport.InvalidDownloadLink	Der Download-Link ist ungültig oder abgelaufen
Admin.ImportExport.InvalidChunk	Content-Range, uploadId oder die Länge des Teilstücks sind ungültig
Admin.ImportExport.UploadNotFound	Der Upload existiert nicht
Admin.ImportExport.UploadInProgress	Der Upload läuft noch
Admin.ImportExport.UploadAlreadyCompleted	Der Upload ist bereits abgeschlossen
Admin.ImportExport.UploadTotalChanged	Die Gesamtgrösse des Uploads hat sich geändert
Admin.ImportExport.UploadChunkOutOfOrder	Das Teilstück passt nicht zur bisherigen Reihenfolge
Admin.ImportExport.ImportBusy	Eine andere Anfrage bearbeitet den Import gerade. Den Aufruf später wiederholen
Admin.ImportExport.InvalidImportState	Der Import lässt den verlangten Schritt in seinem aktuellen Zustand nicht zu

Ohne spezifischen Code steht bei 400, 401, 403 und 404 der allgemeine Code, bei allen 5xx TechnicalError und bei den übrigen Statuscodes die Form Http<Status>, etwa Http409 oder Http413.

Kompatibilität

• v2-Endpunkte behalten ihre bisherigen Statuscodes, ausser dass ein serverseitiger Abbruch neu 500 statt eines leeren 200 ergibt. Fehler aus der gemeinsamen Fehlerbehandlung beantworten sie ebenfalls mit application/problem+json, und in ihren Ausführungsberichten entfällt InternalMessage. Integrationen, die bisher message und isError oder einen leeren Antwortkörper ausgewertet haben, auf status, code und detail umstellen.
• SCIM-Endpunkte verwenden weiterhin die Fehlerantworten des SCIM-Standards.
• …/Admin/Fields und …/Admin/Search beantworten Bindungsfehler (ungültiger JSON-Body, ungültiger Query-Wert) mit dem ASP.NET-Standardformat ValidationProblemDetails, ohne code und correlationId.