Öffentliche API

Referenzdokumentation der Suivi-APIs

8 Min. Lesezeit

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 angereichert wurde.

API Board Mapping

Die BoardMapping-API ermöglicht:

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

API Boards

Die Boards-API ermöglicht es, Aktionen im Zusammenhang mit Boards durchzuführen, wie zum Beispiel:

  • Aktualisierung der Rollen der angegebenen Mitglieder (Benutzer und/oder Team),
  • Suche nach der Liste der Boards eines Arbeitsbereichs,
  • Eine Board-Ansicht nach ihrem Namen suchen,
  • Die CSV-Import-Zuordnungen 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 zu einem 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 gemeinsamen Status 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,
  • Eine Übersicht der verknüpften Boards bereitstellen, die beim Duplizieren eines Boards mitkopiert werden,
  • Ein Board und alle damit verknüpften Boards duplizieren,
  • Die Verknüpfungen zwischen zwei Boards überprüfen.

API BoardWebHook

Die BoardWebhook-API ermöglicht Folgendes:

  • Abrufen der Webhooks eines Boards anhand der Board-ID,
  • Abrufen der Webhooks eines Boards anhand der Webhook-ID,
  • Einen Webhook hinzufügen,
  • Einen Webhook löschen,
  • Einen Webhook auslösen,
  • Einen Webhook stoppen.

API Book

Die API Book ermöglicht:

  • Anpassen des Hintergrunds des Books mit einem Bild, das per URL oder durch eine im Blob-Speicher übertragene Datei bereitgestellt wird,
  • Anpassen der Logos des Books (klein und groß),
  • Das Thema des Books anpassen (hell, einfarbig, Bild),
  • Die Primärfarbe des Books bei einfarbigem Thema anpassen,
  • Ü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 erfahren.

API Tenants

Die API Tenants ermöglicht es:

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

API-Benutzer

Die Users-API ermöglicht Folgendes:

  • Suche nach einem Benutzer anhand von Name, Vorname und E-Mail-Adresse,
  • Erstellen und Bearbeiten eines Benutzers

API Workspaces

Die Workspaces-API ermöglicht Folgendes:

  • Suche nach der Liste der für einen Benutzer zugänglichen Workspaces,
  • Die Rollen Admin, Mitwirkender oder Besucher eines Benutzers in einem Workspace ändern,
  • 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 dass es immer nur einen API-Schlüssel pro Tenant gibt (der alte Schlüssel wird daher deaktiviert).

Auf die Swagger-API zugreifen

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 angereichert wurde.

Dieser Schlüssel ist erforderlich, um sich mit der Swagger-API von Suivi zu verbinden, wie z. B.:

🔐 API-Schlüssel: my-api-key Dieser Schlüssel muss im user-api-key-Header all 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.

Änderung des Hintergrundbilds 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 und sich in der URL der Anfrage befindet
  • 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 und sich in der URL der Anfrage befindet
  • Das Bild als Datei im Hauptteil der Anfrage

Beispiel:

Änderung des Logos eines Books

Bei dieser Methode müssen zwei Logos hochgeladen werden:

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 '[email protected];type=image/jpeg'
  • Das klassische Logo, das im 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 und sich in der URL der Anfrage befindet
  • Das Bild in Form einer Datei im Anfragekörper für das klassische Logo
  • Das Bild in Form einer Datei im Anfragekörper für das responsive Logo

Beispiel:

Änderung des Themas

Es gibt drei Arten von Themen 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 '[email protected];type=image/png' \  -F '[email protected];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 erhält ein Banner in der ausgewählten Farbe
  • Transparent: Das Banner wird transparent sein und das Hintergrundbild durchscheinen lassen

Die Farben sind in einer Schlüssel-Wert-Tabelle definiert, die Sie über den dedizierten Endpoint abrufen können (siehe Abschnitt „Abrufen der Theme-Farben

  • Die ID des Books, das geändert werden soll und sich in der URL der Anfrage befindet
  • Das im Anfragekörper übermittelte Theme. 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:

Ändern 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 angegebene 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 Secret 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, abhängig davon, 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 Anfragekörper

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

    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

War diese Seite hilfreich?