Öffentliche API

Referenzdokumentation der Suivi-APIs

8 Min. Lesezeit

Auf dieser Seite:

    Liste der verfügbaren APIs

    Dieser Abschnitt beschreibt die Liste der von Suivi angebotenen APIs. Diese Liste ist über die URL Ihrer Website zugänglich, indem Sie am Ende swagger eingeben (z. B.: https://domain.suivi.co/swagger).

    Beachten Sie, dass die Swagger-Seite mit dem Schema jeder verfügbaren Root erweitert wurde.

    API Board Mapping

    Die BoardMapping-API ermöglicht:

    • Ein Board-Mapping nach einem wiederkehrenden Import hinzufügen
    • Ein Board-Mapping aktualisieren,
    • Ein Board-Mapping löschen.

    API Boards

    Die Boards-API ermöglicht es, Aktionen in Bezug auf Boards durchzuführen, wie zum Beispiel:

    • Aktualisierung der Rollen der angegebenen Mitglieder (Benutzer und/oder Team),
    • Die Liste der Boards eines Arbeitsbereichs suchen,
    • Die Ansicht eines Boards anhand seines Namens suchen,
    • Die CSV-Import-Mappings eines Boards suchen,
    • Ein Board im CSV-Format exportieren,
    • Die Liste der Abschnitte eines Boards abrufen
    • Die Liste der Ansichten eines Boards abrufen
    • Die Rolle eines Benutzers in eine Admin-, Mitwirkenden- oder Besucherrolle ändern
    • Benutzer in ein Board einladen und ihnen eine Rolle zuweisen,
    • CSV-Daten in ein Board importieren,
    • Ein Board kopieren,
    • Ein Board von einer Sequenznummer kopieren,
    • Den Freigabestatus einer Ansicht ändern,
    • Den Freigabestatus der Ansichten eines Boards kennen,
    • Die Variablen eines Boards ändern,
    • Die Liste der in einem Board verwendeten Variablen abrufen,
    • Die Liste der in einem Board verwendeten Verbindungen abrufen,
    • Die Verbindungen eines Boards ändern,
    • Einen Überblick über die verknüpften Boards geben, die beim Duplizieren eines Boards dupliziert werden,
    • Ein Board und alle seine verknüpften Boards duplizieren,
    • Die Verknüpfungen zwischen zwei Boards überprüfen.

    API BoardWebHook

    Die BoardWebhook-API ermöglicht:

    • Die Webhooks eines Boards anhand der Board-ID abzurufen,
    • Webhooks eines Boards anhand der Webhook-Kennung abrufen,
    • Einen Webhook hinzufügen,
    • Einen Webhook löschen,
    • Einen Webhook starten,
    • Einen Webhook stoppen.

    API Book

    Die Book-API ermöglicht:

    • Den Hintergrund des Books mit einem Bild anzupassen, das über eine URL oder eine im Blob-Storage übertragene Datei bereitgestellt wird,
    • Anpassen der Book-Logos (klein und groß),
    • Anpassen des Book-Themas (hell, einfarbig, Bild),
    • Anpassen der Primärfarbe des Books bei einfarbigem Thema,
    • Überprüfen, ob ein Benutzer berechtigt ist, ein Book und ein Book-Element zu sehen.

    API Context

    Die API Context ermöglicht es, den Kontext des aktuellen Benutzers zu ermitteln.

    API Tenants

    Die Tenants-API ermöglicht:

    • Suche nach einem Tenant nach Name (exakt),
    • Suche nach der Liste der für einen Benutzer zugänglichen Tenants,
    • Aktualisieren der Benutzerrollen des Mandanten (Administrator, Mitwirkender und Besucher),
    • Einen Benutzer einladen und ihm eine Rolle für einen Mandanten zuweisen,
    • Einen neuen Mandanten erstellen.

    API Users

    Die Users-API ermöglicht:

    • Suche nach einem Benutzer nach Name, Vorname und E-Mail-Adresse,
    • Benutzer erstellen, bearbeiten

    API Workspaces

    Die Workspaces-API ermöglicht:

    • Suchen Sie nach der Liste der für einen Benutzer zugänglichen Workspaces,
    • Ändern Sie die Rollen Admin, Mitwirkender oder Besucher eines Benutzers in einem Workspace,
    • Einen Benutzer einladen und ihm eine Rolle in einem Workspace zuweisen,
    • Einen neuen Workspace erstellen.

    Authentifizierung und API-Zugriff

    Einen API-Schlüssel erhalten

    Die Verbindung zu den Suivi-APIs erfordert die Angabe eines API-Schlüssels, der einem Benutzerkonto vom Typ Admin des Tenants zugeordnet ist.

    Um diesen Schlüssel zu finden, klicken Sie einfach auf den Avatar im Arbeits-Tenant und wählen Sie > Mein Profil bearbeiten, Registerkarte API-Schlüssel.

    Beachten Sie, dass es möglich ist, einen neuen Schlüssel zu generieren, aber es gibt immer nur einen API-Schlüssel pro Tenant (der alte Schlüssel wird daher deaktiviert).

    Zugriff auf Swagger-APIs

    Dieser Abschnitt beschreibt die Liste der von Suivi angebotenen APIs. Diese Liste ist über die URL Ihrer Website zugänglich, indem Sie am Ende swagger eingeben (z.B.: https://domain.suivi.co/swagger).

    Beachten Sie, dass die Swagger-Seite mit dem Schema jeder verfügbaren Root erweitert wurde.

    Dieser Schlüssel wird benötigt, um sich mit der Swagger-API von Suivi zu verbinden, wie zum Beispiel:

    🔐 API-Schlüssel: my-api-key Dieser Schlüssel muss im user-api-key-Header aller Ihrer Anfragen enthalten sein.

    Book (Portal)

    Der Abschnitt Book umfasst alle Endpunkte, mit denen Sie das Erscheinungsbild und den Inhalt eines Books in Ihrer Anwendung anpassen können.

    Ändern des Hintergrundbildes eines Books

    Es gibt zwei Möglichkeiten, das Hintergrundbild zu ändern:

    • Durch Senden der URL eines im Internet verfügbaren Bildes
    • Durch Hochladen einer Datei

    Änderung per URL

    Methode: PUT

    URL: public-api/Book/{BookId}/BackgroundImage

    Parameter:

    • Die ID des Books, das geändert werden soll, befindet sich in der URL der Anfrage
    • Das JSON im Anfragekörper, das die URL des Bildes enthält

    Anfragekörper:

    Beispiel:

    Änderung durch Hochladen eines Bildes

    Methode: POST

    URL: public-api/Book/{BookId}/BackgroundImageUpload

    Parameter:

    {  "ImageUrl": "string"}
    curl -X 'PUT' \  '[https://localhost:5001/public-api/Book/02F5GFJM403K9N9B8TCWTHAB4A/BackgroundImage](https://localhost:5001/public-api/Book/02F5GFJM403K9N9B8TCWTHAB4A/BackgroundImage)' \  -H 'accept: */*' \  -H 'user-api-key: my-api-key' \  -H 'Content-Type: application/json' \  -d '{  "ImageUrl": "[https://www.image.fr/mon_image.png](https://www.image.fr/mon_image.png)"}'
    • Die ID des Books, das geändert werden soll, befindet sich in der URL der Anfrage
    • Das Bild in Form einer Datei im Anfragekörper

    Beispiel:

    Änderung des Logos eines Books

    Es gibt zwei Logos, die in dieser Methode hochgeladen werden müssen:

    curl -X 'POST' \  '[https://localhost:5001/public-api/Book/02F5GFJM403K9N9B8TCWTHAB4A/BackgroundImageUpload](https://localhost:5001/public-api/Book/02F5GFJM403K9N9B8TCWTHAB4A/BackgroundImageUpload)' \  -H 'accept: */*' \  -H 'user-api-key: my-api-key' \  -H 'Content-Type: multipart/form-data' \  -F 'BackgroundImageFile=@background-photo.jpg;type=image/jpeg'
    • Das klassische Logo, das auf dem Book angezeigt wird
    • Das responsive Logo für die mobile Anzeige

    Methode: POST

    URL: public-api/Book/{BookId}/Logo

    Parameter:

    • Die ID des Books, das geändert werden soll, befindet sich in der URL der Anfrage
    • Das Bild als Datei im Anfragekörper für das klassische Logo
    • Das Bild als Datei im Anfragekörper für das responsive Logo

    Beispiel:

    Änderung des Themes

    Es gibt drei Arten von Themes für ein Book:

    curl -X 'POST' \  '[https://localhost:5001/public-api/Book/02F5GFJM403K9N9B8TCWTHAB4A/Logo](https://localhost:5001/public-api/Book/02F5GFJM403K9N9B8TCWTHAB4A/Logo)' \  -H 'accept: */*' \  -H 'user-api-key: my-api-key' \  -H 'Content-Type: multipart/form-data' \  -F 'LogoFile=@logo.png;type=image/png' \  -F 'SmallLogoFile=@responsive-logo.png;type=image/png'
    • Light: Das Book hat ein weißes Banner auf der linken Seite mit einer Farbe der Titel beim Überfahren mit der Maus
    • Dark: Das Book hat ein Banner in der ausgewählten Farbe
    • Transparent: Das Banner ist transparent und lässt das Hintergrundbild durchscheinen

    Die Farben sind in einem Schlüssel-Wert-Array definiert, das Sie über den dedizierten Endpoint abrufen können (siehe Abschnitt "Abrufen der Theme-Farben" weiter unten).

    Methode: PUT

    URL: public-api/Book/{BookId}/Theme

    Parameter:

    • Die ID des Books, das geändert werden soll und sich in der URL der Anfrage befindet
    • Das Theme, das im Anfrage-Body übermittelt wird. Mögliche Werte:
      • Light
      • Dark
      • Transparent
    • Die im Anfragekörper übermittelte Farbe in Form einer Ganzzahl, die dem Index der gewünschten Farbe im von der API bereitgestellten Farbarray entspricht

    Anfragekörper:

    Beispiel:

    Abrufen der Theme-Farben

    Abrufen der verfügbaren Farben für das Theme eines Books. Die API gibt ein Array von Schlüssel-Wert-Paaren zurück, das den Index und den hexadezimalen Wert der zugehörigen Farbe enthält.

    Methode: GET

    URL: public-api/Book/ColorPalette

    Antwort:

    Beispiel:

    Board

    Der Abschnitt Board umfasst die Endpunkte zur Verwaltung der Variablen und Verbindungen eines Boards.

    Abrufen der Variablen

    Es ist möglich, alle Variablen eines Boards abzurufen.

    Methode: GET

    URL: public-api/Boards/{BoardId}/variables

    Parameter:

    {  "Theme": "string",  "ColorIndex": 0}
    curl -X 'PUT' \  '[https://localhost:5001/public-api/Book/02F5GFJM403K9N9B8TCWTHAB4A/Theme](https://localhost:5001/public-api/Book/02F5GFJM403K9N9B8TCWTHAB4A/Theme)' \  -H 'accept: */*' \  -H 'user-api-key: my-api-key' \  -H 'Content-Type: application/json' \  -d '{  "Theme": "Transparent",  "ColorIndex": 5}'
    {  "0": "#000000",  "1": "#303E4D",  "2": "#667684",  "3": "#B5BCC2",  "4": "#0652A7",  "5": "#3082B7",  "...": "..."}
    curl -X 'GET' \  '[https://localhost:5001/public-api/Book/ColorPalette](https://localhost:5001/public-api/Book/ColorPalette)' \  -H 'accept: */*' \  -H 'user-api-key: my-api-key'
    • Die ID des Boards, die sich in der URL der Anfrage befindet

    Antwort:

    Beispiel:

    Änderung der Variablen

    {  "Var01": "Val01",  "Var02": "NewVal02",  "Var03": "Val03"}
    curl -X 'GET' \  '[https://localhost:5001/public-api/Boards/01F5GFJM403K9N9B8TCWTHAB4A/variables](https://localhost:5001/public-api/Boards/01F5GFJM403K9N9B8TCWTHAB4A/variables)' \  -H 'accept: */*' \  -H 'user-api-key: my-api-key'
    Symbol
    Wichtig

    Die bereitgestellte Liste ersetzt die vorhandenen Variablen. Es wird empfohlen, die Variablen zunächst abzurufen und dann die vollständige Liste der gewünschten Variablen zu senden.

    Methode: PUT

    URL: public-api/Boards/{BoardId}/variables

    Parameter:

    • Die ID des Boards, die sich in der URL der Anfrage befindet
    • JSON mit der Liste der Variablen im Anfragekörper

    Anfragekörper:

    Beispiel:

    Abrufen der Verbindungen

    Es ist möglich, die Verbindungen eines Boards abzurufen.

    {  "var1": "Plop",  "var2": "65536"}
    curl -X 'PUT' \  '[https://localhost:5001/public-api/Boards/01F5GFJM403K9N9B8TCWTHAB4A/variables](https://localhost:5001/public-api/Boards/01F5GFJM403K9N9B8TCWTHAB4A/variables)' \  -H 'accept: */*' \  -H 'user-api-key: my-api-key' \  -H 'Content-Type: application/json' \  -d '{  "var1": "Plop",  "var2": "65536"}'
    Symbol
    Hinweise

    Sensible Informationen vom Typ Geheimnis für Tokens oder Header-Werte werden von der API nicht angezeigt.

    Die angezeigte Antwort berücksichtigt die beiden in der Anwendung vorhandenen Verbindungstypen:

    • Azure DevOps-Verbindung
    • HTTP-Verbindung

    Methode: GET

    URL: public-api/Boards/{BoardId}/connections

    Parameter:

    • Die ID des Boards, die sich in der URL der Anfrage befindet

    Beispiel:

    Antwort:

    Änderung einer Verbindung

    Die Änderung einer Verbindung ist möglich, erfordert jedoch die Einhaltung bestimmter Regeln. Dazu benötigen wir zunächst die ID der Verbindung, die über die API abgerufen werden kann, und müssen dann ein korrekt konfiguriertes JSON bereitstellen, je nachdem, was wir tun möchten.

    curl -X 'GET' \  '[https://localhost:5001/public-api/Boards/01F5GFJM403K9N9B8TCWTHAB4A/connections](https://localhost:5001/public-api/Boards/01F5GFJM403K9N9B8TCWTHAB4A/connections)' \  -H 'accept: */*' \  -H 'user-api-key: my-api-key'
    {  "01JE6DY43AC7R7S2TPDAPJJ16E": {    "Id": "01JE6DY43AC7R7S2TPDAPJJ16E",    "Name": "TestFixed",    "Type": "AzureDevOps",    "Properties": {      "Organization": "statshvss",      "PersonalToken": "***"    }  },  "01JHJS7BQKH6SHMBMR7JFTNAFY": {    "Id": "01JHJS7BQKH6SHMBMR7JFTNAFY",    "Name": "TestHttp",    "Type": "Http",    "Properties": {      "BaseUrl": "[https://www.google.com](https://www.google.com)",      "Headers": [        "C",        "B"      ]    }  }}
    Symbol
    Wichtig

    Der Typ muss immer im JSON beibehalten werden, auch wenn dieser nicht geändert wird.

    Mögliche Aktionen:

    • Ein Attribut hinzufügen
    • Den Wert eines Attributs ändern
    • Ein Attribut löschen

    Methode: PUT

    URL: public-api/Boards/{BoardId}/connections/{ConnectionId}

    Parameter:

    • Die ID des Boards, die sich in der URL der Anfrage befindet
    • Die ID des Connectors, die sich in der URL der Anfrage befindet
    • JSON im Body der Anfrage

    Ein Attribut hinzufügen

    Das JSON muss Folgendes enthalten, um Attribute hinzuzufügen:

    • Hinzufügen eines Attributs "BaseUrl" mit dem Wert "hello"
    • Hinzufügen eines neuen Headers namens "X-Custom-Header" mit dem Wert "maValeur"

    Anfragekörper:

    Beispiel:

    Ein Attribut aktualisieren

    Hier aktualisiere ich mein Attribut BaseUrl mit einem neuen Wert und aktualisiere meinen Header X-Custom-Header mit einem neuen Wert:

    Anfragekörper:

    Beispiel:

    Ein Attribut löschen

    Hier lösche ich den Header X-Custom-Header:

    Anfragekörper:

    Beispiel:

    {  "Type": "Http",  "BaseUrl": {    "NewValue": "hello"  },  "Headers": {    "X-Custom-Header": {      "Action": "Add",      "Value": "maValeur"    }  }}
    curl -X 'PUT' \  '[https://localhost:5001/public-api/Boards/01F5GFJM403K9N9B8TCWTHAB4A/connections/01JHJS7BQKH6SHMBMR7JFTNAFY](https://localhost:5001/public-api/Boards/01F5GFJM403K9N9B8TCWTHAB4A/connections/01JHJS7BQKH6SHMBMR7JFTNAFY)' \  -H 'accept: */*' \  -H 'user-api-key: my-api-key' \  -H 'Content-Type: application/json' \  -d '{    "Type": "Http",    "BaseUrl": {      "NewValue": "hello"    },    "Headers": {      "X-Custom-Header": {        "Action": "Add",        "Value": "maValeur"      }    }  }'
    {  "Type": "Http",  "BaseUrl": {    "NewValue": "hello"  },  "Headers": {    "X-Custom-Header": {      "Action": "Update",      "Update": {        "NewValue": "Plop"      }    }  }}
    curl -X 'PUT' \  '[https://localhost:5001/public-api/Boards/01F5GFJM403K9N9B8TCWTHAB4A/connections/01JHJS7BQKH6SHMBMR7JFTNAFY](https://localhost:5001/public-api/Boards/01F5GFJM403K9N9B8TCWTHAB4A/connections/01JHJS7BQKH6SHMBMR7JFTNAFY)' \  -H 'accept: */*' \  -H 'user-api-key: my-api-key' \  -H 'Content-Type: application/json' \  -d '{    "Type": "Http",    "BaseUrl": {      "NewValue": "hello"    },    "Headers": {      "X-Custom-Header": {        "Action": "Update",        "Update": {          "NewValue": "Plop"        }      }    }  }'
    {  "Type": "Http",  "Headers": {    "X-Custom-Header": {      "Action": "Remove"    }  }}
    curl -X 'PUT' \  '[https://localhost:5001/public-api/Boards/01F5GFJM403K9N9B8TCWTHAB4A/connections/01JHJS7BQKH6SHMBMR7JFTNAFY](https://localhost:5001/public-api/Boards/01F5GFJM403K9N9B8TCWTHAB4A/connections/01JHJS7BQKH6SHMBMR7JFTNAFY)' \  -H 'accept: */*' \  -H 'user-api-key: my-api-key' \  -H 'Content-Type: application/json' \  -d '{    "Type": "Http",    "Headers": {      "X-Custom-Header": {        "Action": "Remove"      }    }  }'

    Verwandte Artikel
    Hat dies Ihre Frage beantwortet?