Publiczne API

Dokumentacja referencyjna API Suivi

8 min czytania

Lista dostępnych API

Ta sekcja opisuje listę API oferowanych przez Suivi. Lista ta jest dostępna pod adresem URL Twojej witryny po wpisaniu swagger na końcu (np.: https://domain.suivi.co/swagger).

Należy zauważyć, że strona swagger została wzbogacona o schemat każdego dostępnego root.

API Board Mapping

API BoardMapping umożliwia:

  • Dodanie mapowania tablicy po cyklicznym imporcie
  • Zaktualizować mapowanie tablicy,
  • Usunąć mapowanie tablicy.

API Tablic

API Boards umożliwia wykonywanie działań związanych z tablicami, takich jak:

  • Aktualizacja ról określonych członków (użytkownika i/lub zespołu),
  • Wyszukiwanie listy tablic w przestrzeni roboczej,
  • Wyszukiwanie widoku tablicy według nazwy,
  • Wyszukiwanie mapowań importu CSV tablicy,
  • Eksportowanie tablicy do formatu CSV,
  • Pobrać listę sekcji tablicy
  • Pobrać listę widoków tablicy
  • Zmienić rolę użytkownika na rolę typu administrator, współtwórca lub gość
  • Zapraszać użytkowników do tablicy i przypisywać im role,
  • Importować dane CSV do tablicy,
  • Kopiować tablicę,
  • Skopiować board z numeru sekwencyjnego,
  • Zmienić status udostępniania widoku,
  • Poznać udostępniony status widoków tablicy,
  • Modyfikować zmienne tablicy,
  • Odnaleźć listę zmiennych używanych w tablicy,
  • Znaleźć listę połączeń używanych w tablicy,
  • Modyfikować połączenia tablicy,
  • Zapewnić podgląd powiązanych tablic, które zostaną zduplikowane podczas duplikowania tablicy,
  • Duplikować tablicę i wszystkie powiązane z nią tablice,
  • Sprawdzić powiązania między dwiema tablicami.

API BoardWebHook

API BoardWebhook pozwala na:

  • Poznanie webhooków tablicy według identyfikatora tablicy,
  • Poznanie webhooków tablicy według identyfikatora webhooka,
  • Dodać webhook,
  • Usunąć webhook,
  • Uruchomić webhook,
  • Zatrzymać webhook.

API Book

API Book umożliwia:

  • Dostosować tło książki za pomocą obrazu dostarczonego przez URL lub przez plik przesłany do magazynu blob,
  • Dostosować loga książki (małe i duże),
  • Dostosować motyw booka (jasny, jednolity, obraz),
  • Dostosować kolor podstawowy booka w przypadku motywu jednolitego,
  • Sprawdzić, czy użytkownik ma prawo do przeglądania booka i elementu booka.

API Context

API Context umożliwia poznanie kontekstu związanego z bieżącym użytkownikiem.

API Tenants

API Tenants umożliwia:

  • Wyszukiwanie najemcy według nazwy (dokładnej),
  • Wyszukiwanie listy najemców dostępnych dla użytkownika,
  • Aktualizacja ról użytkowników najemcy (Administrator, Współautor i Gość),
  • Zaproszenie użytkownika i nadanie mu roli w dzierżawie,
  • Utworzenie nowej dzierżawy.

Użytkownicy API

API Users umożliwia:

  • Wyszukiwanie użytkownika po nazwisku, imieniu i adresie e-mail,
  • Tworzenie i modyfikowanie użytkownika

API Workspaces

API Workspaces umożliwia:

  • Wyszukiwanie listy przestrzeni roboczych dostępnych dla użytkownika,
  • Modyfikować role Administrator, Współpracownik lub Gość użytkownika w przestrzeni roboczej,
  • Zaprosić użytkownika i nadać mu rolę w przestrzeni roboczej,
  • Utwórz nowy workspace.

Uwierzytelnianie i dostęp do API

Uzyskanie klucza API

Połączenie z API Suivi wymaga podania klucza API powiązanego z kontem użytkownika typu Admin danego tenanta.

Aby znaleźć ten klucz, wystarczy kliknąć na awatar w workspace tenanta i wybrać > Edytuj mój profil, zakładka API key.

Należy pamiętać, że możliwe jest wygenerowanie nowego klucza, ale dla tenanta zawsze istnieje tylko jeden klucz API (stary klucz zostaje więc dezaktywowany).

Dostęp do API Swagger

Ta część opisuje listę API oferowanych przez Suivi. Lista ta jest dostępna pod adresem URL Twojej witryny po wpisaniu swagger na końcu (np.: https://domain.suivi.co/swagger).

Należy zauważyć, że strona swagger została wzbogacona o schemat każdego dostępnego root.

Ten klucz będzie Ci potrzebny do połączenia z API Swagger Suivi, takim jak:

🔐 Klucz API: my-api-key Ten klucz musi być zawarty w nagłówku user-api-key wszystkich Twoich żądań.

Book (portal)

Sekcja Book grupuje wszystkie endpointy umożliwiające personalizację wyglądu i zawartości book w Twojej aplikacji.

Modyfikacja obrazu tła book

Istnieją dwa sposoby zmiany obrazu tła:

  • Wysyłając adres URL obrazu dostępnego w internecie
  • Przesyłając plik

Modyfikacja przez URL

Metoda: PUT

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

Parametry:

  • ID książki, którą chcemy zmodyfikować, znajdujące się w adresie URL żądania
  • JSON w treści żądania zawierający adres URL obrazu

Treść żądania:

Przykład:

Modyfikacja przez przesłanie obrazu

Metoda: POST

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

Parametry:

{  "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)"}'
  • ID booka, który chcemy zmodyfikować, znajdujące się w URL żądania
  • Obraz w postaci pliku w treści żądania

Przykład:

Modyfikacja logo booka

W tej metodzie należy załadować dwa loga:

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'
  • Klasyczne logo wyświetlane w book
  • Logo responsywne do wyświetlania mobilnego

Metoda: POST

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

Parametry:

  • ID booka, który chcemy zmodyfikować, znajdujące się w adresie URL żądania
  • Obraz w formie pliku w treści żądania dla klasycznego logo
  • Obraz w formie pliku w treści żądania dla responsywnego logo

Przykład:

Modyfikacja motywu

Istnieją trzy typy motywów dla booka:

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: Book będzie miał biały pasek po lewej stronie z kolorem tytułów przy najechaniu myszką
  • Ciemny: Book będzie miał baner w wybranym kolorze
  • Przezroczysty: Baner będzie przezroczysty i pozwoli zobaczyć obraz tła

Kolory są zdefiniowane w tablicy klucz-wartość, którą można pobrać za pomocą dedykowanego endpointu (zobacz sekcję „Pobieranie kolorów motywu" poniżej).

Metoda: PUT

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

Parametry:

  • ID booka, który chcemy zmodyfikować, znajdujące się w adresie URL żądania
  • Motyw przekazany w treści żądania. Możliwe wartości:
    • Light
    • Dark
    • Transparent
  • Kolor przekazany w treści żądania, w postaci liczby całkowitej odpowiadającej indeksowi koloru, który chcemy wybrać z tablicy kolorów dostarczonej przez API

Treść żądania:

Przykład:

Pobieranie kolorów motywu

Pobieranie dostępnych kolorów dla motywu booka. API zwraca tablicę par klucz-wartość zawierającą indeks i wartość szesnastkową powiązanego koloru.

Metoda: GET

URL: public-api/Book/ColorPalette

Odpowiedź:

Przykład:

Board

Sekcja Board grupuje endpointy umożliwiające zarządzanie zmiennymi i połączeniami boarda.

Pobieranie zmiennych

Możliwe jest pobranie wszystkich zmiennych boarda.

Metoda: GET

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

Parametry:

{  "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'
  • ID boarda, które znajduje się w URL żądania

Odpowiedź:

Przykład:

Modyfikacja zmiennych

{  "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'
Ważne

Podana lista zastąpi istniejące zmienne. Zaleca się najpierw pobrać zmienne, a następnie wysłać pełną listę zmiennych, które chcemy mieć.

Metoda: PUT

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

Parametry:

  • ID tablicy, które znajduje się w adresie URL żądania
  • JSON z listą zmiennych w treści żądania

Treść żądania:

Przykład:

Pobieranie połączeń

Możliwe jest pobranie połączeń tablicy.

{  "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"}'
Uwagi

Poufne informacje typu secret dla tokenów lub wartości nagłówków nie są wyświetlane przez API.

Wyświetlana odpowiedź uwzględnia dwa typy połączeń istniejących w aplikacji:

  • Połączenie Azure DevOps
  • Połączenie HTTP

Metoda: GET

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

Parametry:

  • ID tablicy, które znajduje się w adresie URL żądania

Przykład:

Odpowiedź:

Modyfikacja połączenia

Modyfikacja połączenia jest możliwa, ale wymaga przestrzegania pewnych zasad. W tym celu najpierw potrzebujemy ID połączenia, które można pobrać za pomocą API, a następnie należy dostarczyć poprawnie skonfigurowany JSON w zależności od tego, co chcemy zrobić.

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"      ]    }  }}
Ważne

Należy zawsze zachować typ w JSON, nawet jeśli nie będzie on modyfikowany.

Możliwe działania:

  • Dodaj atrybut
  • Zmień wartość atrybutu
  • Usuń atrybut

Metoda: PUT

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

Parametry:

  • ID tablicy, które znajduje się w adresie URL żądania
  • ID konektora, które znajduje się w adresie URL żądania
  • JSON w treści żądania

Dodawanie atrybutu

Oto co powinien zawierać JSON, aby dodać atrybuty:

  • Dodanie atrybutu "BaseUrl" z wartością "hello"
  • Dodanie nowego nagłówka o nazwie "X-Custom-Header" z wartością "maValeur"

Treść żądania:

Przykład:

Aktualizacja atrybutu

Tutaj aktualizuję mój atrybut BaseUrl nową wartością i aktualizuję mój nagłówek X-Custom-Header nową wartością:

Treść żądania:

Przykład:

Usunięcie atrybutu

Tutaj usuwam nagłówek X-Custom-Header:

Treść żądania:

Przykład:

{  "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"      }    }  }'

Powiązane artykuły

Czy ta strona była pomocna?