Zum Hauptinhalt springen

Erkunden der API

Um sich mit der REST-Schnittstelle vertraut zu machen, können Sie unsere interaktive API-Dokumentationsseite nutzen, die auf Swagger basiert. Hier werden die verfügbaren Dienste aufgelistet und Beispiele für ihre Parameter und Ergebnisse gezeigt. Sie ermöglicht es Ihnen auch, die REST-Endpunkte per Mausklick direkt aufzurufen:

The fallback content to display on prerendering

Um es zu verwenden, gehen Sie zu "https://<Ihr.portal.url>/swagger/ui/index". Die Seite selbst kann ohne Anmeldung geöffnet werden.

Authentifizieren​

Die meisten Webdienste erfordern ein OAuth 2.0-Bearer-Token. Anhand dieses Tokens prüft der Server, ob Sie tatsächlich authentifiziert sind. Der Benutzer, zu dem das Token gehört, benötigt die Berechtigungen, die der jeweilige Endpunkt erfordert.

Wenn Sie im selben Browser im Portal angemeldet sind, trägt die Swagger-Oberfläche Ihr Zugangstoken selbst ein und lädt das Dokument damit neu - Sie müssen nichts tun. Das Portal erneuert sein Token nur, solange eine Portal-Registerkarte geöffnet ist: Bleibt das Feld leer, öffnen Sie einmal das Portal und laden die Swagger-Oberfläche neu.

Andernfalls geben Sie das Token einmal für die ganze Seite ein:

  1. Fügen Sie Bearer <access token> in das Feld in der oberen Leiste rechts neben der Dokument-URL ein (Platzhaltertext Bearer <access token>).
  2. Klicken Sie auf Explore oder drücken Sie Enter.

Das Dokument wird mit dem Token neu geladen, und jedes Try it out! sendet es im Header Authorization mit. Sie können das Token auch über die Schaltfläche mit dem Schloss bei einer geschützten Operation eingeben. Um das Token zu entfernen, leeren Sie das Feld.

Wie Sie das OAuth 2.0-Bearer-Token abrufen

Operationen und Modelle je Inhaltstyp​

Gehört das Token einem Mandantenbenutzer mit der Berechtigung, Inhaltselemente anzuzeigen, enthält das neu geladene Dokument zusätzlich für jeden Inhaltstyp dieses Mandanten eine Gruppe Content: <contenttypename>, z.B. Content: defect (die Namen der Inhaltstypen werden so verwendet, wie sie gespeichert sind, also in Kleinbuchstaben). Diese Gruppen stehen alphabetisch geordnet am Ende der Liste, nach den Gruppen ContentItemSync, ContentTypes und ContentItem. Jede von ihnen listet die Operationen für Inhaltselemente mit bereits eingesetztem Namen des Inhaltstyps auf, z.B. GET /api/content/defect, POST /api/content/defect, GET/PUT/PATCH/DELETE /api/content/defect/{id}, POST /api/content/defect/batch und /batchforce sowie getchanges, export und template/excel.

Nur zum Erkunden und Ausprobieren

Inhaltstypen können jederzeit geändert werden, z.B. von einem Administrator im Portal. Die Operationen und das Modell eines Inhaltstyps ändern sich mit ihm, ohne neue API-Version, sodass ein darauf aufbauender Client nicht mehr funktionieren kann. Verwenden Sie sie, um die API zu erkunden und auszuprobieren. Für Integrationen verwenden Sie die allgemeinen Operationen /api/content/{contentTypeName} (siehe Inhaltselemente): Diese behalten ihre Form. Jede Operation einer Gruppe Content: <contenttypename> wiederholt diese Warnung in ihren Implementation Notes.

Zu jeder dieser Gruppen gehört ein Modell <contenttypename>ContentItemDto, das die Felder eines Elements auflistet:

  • den JSON-Typ und das Format jedes Felds, entsprechend seinem Feldtyp,
  • die erlaubten Werte von Auswahlfeldern (als enum),
  • für jeden Verweis auf ein anderes Inhaltselement den Anzeigetext <field>__title (nur lesbar),
  • die Systemfelder wie _id, contentItemId, externalId, lastModificationTime, isDeleted sowie Ersteller und letzten Bearbeiter.
Hinweis
  • Nur das Titelfeld wird im Modell als required aufgeführt - es ist das einzige Feld, das die API erzwingt. Felder, die im Inhaltstyp als Pflichtfeld markiert sind, weisen in ihrer Beschreibung darauf hin; ein Element kann aber auch ohne sie gespeichert werden, und ein mit GET gelesenes Element lässt Felder ohne Wert weg.
  • Felder der Typen User und Guid sind nicht Teil des JSON der REST-API - weder beim Lesen noch beim Schreiben. Sie werden im Modell nicht aufgeführt.

Die Listen-Operation GET /api/content/<contenttypename> nimmt die OData-v3-Abfrageoptionen $filter, $orderby, $top und $skip als Parameter, sodass Sie Filtern, Sortieren und seitenweises Laden ausprobieren können. Die Beschreibungen von $filter und $orderby listen die Felder des Inhaltstyps so auf, wie sie in einer Abfrage geschrieben werden müssen (erster Buchstabe groß, z.B. Name für das Feld name), dazu die unterstützten Operatoren und Funktionen und die Schreibweise von Werten. Die allgemeine Listen-Operation GET /api/content/{contentTypeName} hat dieselben Parameter, mit einer allgemeinen Beschreibung.

Ohne Token, mit einem ungültigen oder abgelaufenen Token, mit dem Token eines Host-Administrators oder ohne die Berechtigung, Inhaltselemente anzuzeigen, enthält das Dokument wie bisher nur die allgemeinen Operationen /api/content/{contentTypeName}. Diese stehen in jedem Fall zur Verfügung.