Wstęp do interfejsów programistycznych AMAGE

Wstęp

Dokument opisuje interfejsy programistyczne AMAGE, które umożliwiają integrację z systemem AMAGE. Interfejsy pozwalają na dostęp do danych oraz na wykonywanie operacji na danych w systemie AMAGE. Komunikacja realizowana jest przez protokół HTTPS oraz metody REST API. Aby skorzystać z interfejsów programistycznych AMAGE, należy mieć odpowiednie uprawnienia dostępowe oraz klucze dostępu.

Generacja kluczy dostępu - skrót

Aplikacja wykorzystuje klucze dostępu (APIKeys) do tworzenia skrótów autoryzujących dostęp do interfejsu WEB REST API. Definicję uprawnień kluczy realizujemy w interfejsie konfiguracyjnym w sekcji Klucze API.

image 2024 05 22 19 56 17 047
Rysunek 1. Widok listy kluczy API z informacją podstawową o kluczu
image 2024 05 22 19 56 50 499
Rysunek 2. Szczegóły dostępowe klucza API

Po więcej odnieś się do instrukcji użytkownika:

Klucze API, autoryzacja i nagłówki danych

Aby umożliwić dostęp do interfejsu API oraz mieć możliwość komunikacji się poprzez ten interfejs, musimy utworzyć klucze API służące do autoryzacji/podpisywania zapytań, tak aby system AMAGE był w stanie poprawnie rozpoznać zapytanie i udostępnić dane. Wygeneruj klucze API w sekcji konfiguracji i nie zapomnij go aktywować. Zapisz trzy parametry - device-uuid, klucz oraz sekret, które zostaną użyte do generowania podpisu zapytania.

Więcej:

Identyfikacja obiektów/UUID

Obiekty w systemie identyfikują się poprzez swój unikalny identyfikator UUID. W celu pobrania obiektu z systemu należy znać jego UUID. UUID można znaleźć w interfejsie użytkownika, w plikach eksportu, w bazie danych, w logach systemowych. Zwykle w interfejsie użytkownika, dla każdego obiektu pojawia się dodatkowy przycisk w podglądzie danych lub jego edytorze z ikoną (I). Po jego wybraniu wyświetla się informacja o danych identyfikacyjnych obiektu, w tym UUID. Użyj tego UUID do interakcji tam, gdzie wymagane jest podanie UUID.

image 2024 05 26 09 21 39 780
Rysunek 3. Przycisk informacyjny
image 2024 05 26 09 22 10 636
Rysunek 4. Dane identyfikacyjne w tym UUID

Podpis API

Do każdej komunikacji z systemem AMAGE przez interfejs REST wymagane jest dołączenie trzech nagłówków (headers) z danymi:

  • amage-device-uuid - identyfikator urządzenia, dla którego generowany jest podpis

  • amage-api-key - klucz API

  • amage-api-sign - podpis zapytania

Device UUID oraz klucz API podajemy bezpośrednio z wygenerowanego klucza API. Podpis generowany jest na podstawie ścieżki zapytania oraz sekretu klucza API. Podpis jest generowany za pomocą algorytmu SHA-256, a wynik jest przekazywany w postaci binarnej. Następnie wynik jest konwertowany do postaci szesnastkowej i przekazywany jako nagłówek amage-api-sign.

W przypadku zapytań, które zawierają w swojej treści (URL) parametry, należy pamiętać, że do wyliczenia podpisu zapytania używamy tylko samej ścieżki zapytania, bez parametrów. Czyli dla ścieżki rest/api/v1/test/query?param1=1&param2=2 podpis wyliczamy dla ścieżki rest/api/v1/test/query.
Przykład wyliczania podpisu zapytania w języku Python znajduje się w poszczególnych przykładach dla poszczególnych sekcji interfejsów.

Kodowanie znaków

Wszelkie znaki w zapytaniach powinny być odpowiednio zakodowane. W przypadku zapytań GET znaki powinny być zakodowane zgodnie z zasadami URL Encoding.

W przypadku zapytań POST, znaki powinny być zakodowane zgodnie z zasadami JSON Encoding.

Interfejsy programistyczne

Dostępne informacje dotyczące interfejsów REST API podzielone są na sekcje funkcjonalne. Użytkownik po odpowiednim uprawnieniu ma możliwość korzystania z poszczególnych sekcji.

Wybierz sekcję/artykuł: