Definicje API

Funkcjonalność umożliwia utworzenie definicji prostego REST API, za pośrednictwem którego w kontekście wybranego procesu będzie można przeprowadzić integrację zewnętrznego systemu z WEBCON BPS.

1. Informacje podstawowe

Pole Nazwa pozwala wprowadzić nazwę dla tej definicji API. W polu Dokumentacja opcjonalnie wprowadzić opis definicji API, który będzie dostępny w wygenerowanej dokumentacji procesu.
ID jest automatycznie generowanym identyfikatorem definicji API i nie jest uzupełniane przez użytkownika konfigurującego.

2. Tryb działania

Pozwala określić zachowanie, które zostanie uruchomione po wywołaniu zdefiniowanego tu endpoint. Dostępne są opcje:

• Wywołaj automatyzację – udostępnione API z poziomu zewnętrznej aplikacji umożliwi uruchomienie automatyzacji, której definicję nalezy utworzyć na zakładce Automatyzacja. Obsługiwane są wywołania typu POST.

• Pobierz dane ze źródła danych – API umożliwi pobranie wartości z wskazanego źródła. Konfiguracja źródła oraz filtrów dla tego źródła jest dostępna na zakładce Źródło danych. Obsługiwane są wywołania typu GET.

• Pobierz dane z instancji elementu – API umożliwi pobranie wartości ze wskazanego elementu obiegu. Zakres i typ danych zwracanych po wywołaniu endpoint tego typu definiowany jest w zakładce Dane elementu.
  By wskazać którego elementu dane powinny zostać zwrócone, w przy wywołaniu API tego typu, na końcu ścieżki wywoływania podać ID emelentu, np. https://webcon.bps/api/udef/db/1/MyEndpoint/123
  Obsługiwane są wywołania typu GET.

3. Aktywowanie endpoint

Należy zaznaczyć tę opcję by skonfigurowany endpoint był dostępny dla wywołującego go systemu zewnętrznego. Odznaczenie powoduje zachowanie konfiguracji niemniej endpoint nie będzie dostępny la wywołującego go systemu.

4. Adres URL

Pozwala określić adres pod którym definicja API będzie dostępna do wywołania przez zewnętrzny system. Adres jest częściowo generowany automatycznie i będzie miał postać: https://{BPS_Portal}/api/udef/db/{dbId}/MyEndpoint. W tym miejscu konfiguracji należy zdefiniować ostatni człon adresu MyEndpoint. Zmienne {BPS_Portal} oraz {dbId} zostaną uzupełnione automatycznie.
Pełen wygenerowany adres wyświetlany jest pod kontrolką konfiguracji adresu.

Adres endpointu może składać się z kilku podkatalogów rozdzielonych znakiem /. Nazwa każdego z nich może zawierać cyfry, jednak zabronione są nazwy składające się wyłącznie z samych cyfr.

Przykład

Konfiguracja adresu w postaci MyData/v1/invoices
spowoduje udostępnienie API pod adresem https://webconbps.com/api/udef/db/1/MyData/v1/invoices

W przypadku trybu Pobierz dane z instancji elementu wywołanie API wymaga odwołania do elementu obiegu. W takim przypadku do ścieżki wywołania API należy dodać segment zawierającym ID elementu obiegu.

Przykład

https://webconbps.com/api/udef/db/1/MyEndpoint/123

5. Tryb uwierzytelnienia

Przed wywołaniem API wymagane jest uwierzytelnienie systemu wywołującego w WEBCON BPS. Uwierzytelnienie może nastąpić na dwa sposoby:

• Uwierzytelnianie danymi aplikacji (OAuth2) – uwierzytelnienie będzie odbywało się za pomocą tokenu w oparciu o zdefiniowaną aplikację dostępu publicznego. Opis konfiguracji aplikacji dostępu publicznego REST zawiera rozdział Aplikacje z dostępem do API.
  Konfigurując aplikację REST można używać zarówno Kontekstu aplikacji jak i Kontekstu użytkownika. By endpoint mógł być wywoływany w kontekście zdefiniowanego użytkownika w konfiguracji aplikacji REST konieczne jest udzielenie odpowiedniego zakresu uprawnień (scopes).

W przypadku Kontekstu aplikacji są to zakresy uprawnień:
App.UserDefAPI.Read.All - odczyt źródeł danych i danych elementu we wszystkich aplikacjach
App.UserDefAPI.ReadWrite.All - odczyt źródeł danych i danych elementu, użycie automatyzacji i operacje na elemencie w wybranej aplikacji

W przypadku Kontekstu użytkownika są to zakresy uprawnień:
User.UserDefAPI.Read.All - odczyt źródeł danych i danych elementu we wszystkich aplikacjach
User.UserDefAPI.ReadWrite.All - odczyt źródeł danych i danych elementu, użycie automatyzacji i operacje na elemencie we wszystkich aplikacjach
User.UserDefAPI.Read.<AppGuid> - odczyt źródeł danych i danych elementu w wybranej aplikacji
User.UserDefAPI.ReadWrite.<AppGuid> - odczyt źródeł danych i danych elementu, użycie automatyzacji i operacje na elemencie w wybranej aplikacji

• Uwierzytelnianie danymi użytkownika BPS Portal (Cookie) – uwierzytelnianie będzie odbywało się z wykorzystaniem plików cookie z poziomu WEBCON BPS Portal. Ten tryb nie wymaga dodatkowej konfiguracji. Może być użyteczny w przypadku wywoływania endpoint przez kod Java Script z poziomu niestandardowej kontrolki HTML osadzonej na formularzu lub dashboardzie aplikacji, by pobrać lub ustawić jakieś dane z wykorzystaniem API. Dostęp do danych aplikacji i procesu będzie ograniczony zgodnie z uprawnieniami zalogowanego użytkownika w kontekście którego następuje wywołanie endpoint.

Niezależnie od sposobu uwierzytelnienia, użytkownik, w kontekście którego wywoływany jest endpoint, musi posiadać co najmniej uprawnienie Dostęp do aplikacji, aby mieć dostęp do zdefiniowanych endpointów. Dodatkowo, jeśli wywoływane API wykonuje operacje na elementach procesu, użytkownik musi również posiadać odpowiednie uprawnienia do danego procesu lub do danego elementu (np. aby zarejestrować nowy element lub zmodyfikować istniejący).
Warto podkreślić, że posiadanie uprawnień do elementów jedynie na poziomie procesu, bez uprawnień do aplikacji, uniemożliwia wywołanie endpointu.

6. Ograniczenia dostępu

Reguła pozwala zdefiniowac dodatkowe warunki w których endpoint będzie dostępny lub nie. Jeżeli reguła nie została zdefiniowana i pole pozostawiono puste, wywołanie definicji API uzależnione jest od uprawnień użytkownika do aplikacji lub odpowiednich zakresów uprawnień (scope).
Jeżeli użytkownik posiada odpowiednie uprawnienia do aplikacji, a zdefiniowana reguła zwróci wartość POSITIVE, TRUE lub 1, dostęp do endpointu zostanie przyznany. Jeśli reguła zwróci inne wartości, żądanie do API zostanie zablokowane i przy próbie wywołania endpoint zwróci błąd 403.

Regułę ograniczenia dostępu warto stosować w przypadku trybu uwierzytelniania: Uwierzytelnianie danymi użytkownika BPS Portal (Cookie). W tym trybie każdy użytkownik zalogowany w Portalu będzie mógł wywołać endpoint. Uprawnienia do wykonania konkretnej operacji (np. odczytu danych elementu lub wykonania akcji) są weryfikowane na etapie jej realizacji. Niemniej jednak, w sytuacji gdy operacja dotyczy danych globalnych (czyli niezwiązanych z konkretnym elementem), warto ograniczyć dostęp do endpointu tylko do określonej grupy użytkowników.

Dokumentacja OpenAPI endpointów

Dla głównego węzła Definicje API w drzewie nawigacji dostępny jest pasek narzędzi z przyciskiem umożliwiającym wygenerowanie i pobranie definicji utworzonych API w formacie OpenAPI.
Format ten pozwala na łatwe udostępnienie, dokumentowanie oraz testowanie API, zapewniając spójność i zgodność z najlepszymi praktykami w integracji systemów.