Dokument zakłada, że WebApi znajduje się pod adresem IP 127.0.0.1 i na porcie 8080.
Przykładowy adres WebApi w takiej konfiguracji:
http://127.0.0.1:8080/endpoint
\__/ \_______/ \__/ \______/
| | | |
protokół host port scieżka
do zasobu
Wszystkie tokeny mają charakter przykładu i są generowane losowo, nie zadziałają po skopiowaniu.
Uwierzytelnianie
Zanim będzie można korzystać z endpointów WebApi należy utworzyć sesję urządzenia z WebApi.
W tym celu należy wysłać odpowiednio spreparowane zapytanie [GET] na endpoint
http://127.0.0.1:8080/api/Sessions/OpenNewSession?deviceName=<NAZWA>
W parametrze deviceName należy podać nazwę urządzenia dla którego zostanie założona sesja, jest to po prostu dowolna unikatowa nazwa dla sesji. Nie ma większego znaczenia co tam zostanie wpisane.
Następnie należy dodać "Header" do zapytania http z kluczem aplikacji.
Authorization: Application 493EB16D-7029-48AA-BB25-8BA7138D763A
Przykład w Headera zapytania w programie Postman:
Klucz to ciąg znaków w formacie GUID, można go pobrać z następujących miejsc:
•Z konfiguratora aplikacji w zakładce produktu do którego chcemy uzyskać dostęp na przykład dla WebApi Handel znajduje się w zakładce Handel:
•Klucz ten jest również zapisany w wygenerowanym pliku konfiguracyjnym WebApi.config w tagu xml ApplicationGUID
Informacją zwrotną powinien być response http 200 zawierający token w formacie GUID utworzonej sesji:
Autoryzacja
Autoryzacja to proces mający miejsce przed wykonaniem zapytania http przez WebApi, ma na celu zabezpieczenie endpointów przed nieuprawionym dostępem.
W celu uzyskania dostępu do zasobów np listy dokumentów zakupu http://127.0.0.1:8080/api/Purchases trzeba dodać Header z tokenem sesji uzyskanym w kroku uwierzytelnienia:
Authorization: Session d28b139a-ea62-492e-a97b-4fd22b9f2f76
Przykład w Headera zapytania w programie Postman:
Zapytania w kolekcji postman mają odpowiednio oskryptowane zarówno OpenNewSession jak i automatyczne dołączanie Authorization do zapytań więc przy korzystaniu z kolekcji nie trzeba bawić się w ręczne ustawianie identyfikatorów sesji.
Połączenie z WebApi można zweryfikować korzystając z otwartych endpointów WebApi jak http://127.0.0.1:8080/api/Ping
To zapytanie zwróci informację na temat obecnie otwartej firmy w programie i załadowanych modułów .
Endpointy są udokumentowane w klasach rozszerzających typ AdvancedApiController i w deklaracjach interfejsów jak ISessionController, IPurchasesController etc.
Zabezpieczone endpointy w kontrolerach mają atrybut [AuthorizeSession] - dla uwierzytelnienia sesji użytkownika.