Podstawowe funkcjonalności narzędzia Postman na przykładzie vCloud Director
W dzisiejszym świecie aplikacji webowych, termin API (Application Programming Interface) pojawia się niemal nieustannie. Podjęłam się zadania, które w sposób czytelny zobrazuje przebieg pracy z API za pośrednictwem jednego z ciekawszych narzędzi, jakim jest Postman.
API, znane jest jako interfejs przeznaczony dla programistów, tworzących aplikacje internetowe, który określa w jaki sposób poszczególne elementy, bądź warstwy oprogramowania, powinny się ze sobą komunikować. Jednym ze stylów architektonicznych budowania API jest REST (Representational State Transfer), który został zaprojektowany z myślą o wydajnej wymianie danych na drodze klient – serwer. Restowe API wykorzystuje typowe metody HTTP, takie jak POST, GET, PUT, DELETE.
Jednym z narzędzi umożliwiających przesyłanie zapytań (request) i odbieranie odpowiedzi (response) od serwisów internetowych jest bohater niniejszego opracowania, a więc wspomniany – Postman.
Postman, to program, który wyróżnia się intuicyjnym interfejsem oraz prostą obsługą oraz oferuje wiele przydatnych funkcjonalności.
Podstawowe funkcje i elementy narzędzia Postman
W menu bocznym aplikacji możemy zobaczyć historię ostatnio wykonanych requestów, stworzyć nowe API lub kolekcję. Kolekcje dają możliwość przechowywania wykonanych żądań, zatem w dowolnej chwili będziemy mogli je ponownie wykorzystać. Same kolekcje możemy również wyeksportować do repozytorium oraz współdzielić.
Sercem narzędzia Postman jest Workspace, czyli miejsce pozwalające, zarówno na prace indywidulane, jak i na organizację pracy oraz współpracę z resztą zespołu. Dzięki współpracy w przestrzeni roboczej, wszystkie edycje są synchronizowane w czasie rzeczywistym. Workspace pozwala także na grupowanie tworzonych projektów oraz – co najważniejsze – budowanie i wysyłanie żądań. Niezależnie od tego, czy budujemy i testujemy swoje własne API, czy też integrujemy się z innym, możemy wypróbować nasze żądania w Postmanie. Po wysłaniu żądania, program wyświetli odpowiedź otrzymaną z serwera API w szybki i czytelny sposób.
Jak już wspomniałam, Postman daje możliwość wysyłania różnego rodzaju żądań (requests). Do tych najbardziej popularnych z pewnością należą:
- POST – tworzenie nowych zasobów
- PUT – aktualizowanie lub zastępowanie obecnych zasobów
- GET – pobieranie zasobów
- DELETE – usuwanie zasobów
Postman w praktyce – testujemy zmianę motywu vCloud Director
Funkcje i możliwość narzędzia Postman najlepiej jest zobrazować na konkretnych przykładach. Spróbujmy zatem wysłać odpowiednie żądania do API portalu vCloud Director w celu zmiany motywu portalu.
Uwierzytelnianie
Od czego zacząć? Na początek warto zastanowić się nad dostępem do API vCloud Director. Otóż, większość API stosuje metody autoryzacji w celu zapewnienia, że klient żąda bezpiecznego dostępu do danych. Jeśli budujemy własne API, możemy wybrać jeden z wielu modeli autoryzacji. W przypadku integracji z zewnętrznym API, autoryzacja określona jest przez jego dostawcę.
W przypadku portalu vCloud Director posłużymy się autoryzacją typu Bearer Token, co pozwoli nam na uwierzytelnianie za pomocą klucza dostępu. Praktyczność i wygodę takiej autoryzacji wyjaśnimy nieco później. Teraz skupmy się na kolejnych krokach, jakie musimy wykonać.
- Na początku musimy stworzyć środowisko, czyli miejsce, gdzie zdefiniujemy adres naszego API, umieścimy Bearer Token oraz w łatwy sposób będziemy mogli używać ponownie zapisanych żądań. Należy określić nazwę środowiska i zmienną hosta dla instancji vCloud Director.
Po utworzeniu środowiska – należy wybrać je z rozwijanej listy w obszarze roboczym (prawy góry rób obszaru roboczego). Jak na rysunku:
2. Tworzymy żądanie POST z adresem URL: https://{{host}}/api/sessions, w sekcji Headers dodajemy Accept dla application/*+xml;version=32.0
3. W sekcji Tests umieszczamy następujący kod:
var bearer = postman.getResponseHeader(“X-VMWARE-VCLOUD-ACCESS-TOKEN”)
pm.environment.set(“X-VMWARE-VCLOUD-ACCESS-TOKEN”,bearer)
4. W sekcji Authorization wybieramy typ autoryzacji – Basic Auth i wprowadzamy dane logowania do naszego panelu vCloud Director.
5. Po wysłaniu tak przygotowanego żądania powinniśmy otrzymać odpowiedź ze statusem 200. Żądanie możemy zapisać w kolekcji, by móc je jeszcze w przyszłości wykorzystać.
Na tym etapie warto jeszcze zauważyć, że w sekcji Headers odpowiedzi znajduje się X-VMWARE-VCLOUD-ACCESS-TOKEN. Nie będziemy go używać do kolejnych wywołań API. Został on odebrany i zapisany do zmiennej środowiskowej przez kod, jakiego użyliśmy w kroku numer 3.
6. Stwórzmy teraz nowe zapytanie API. Przykładowo, wyślemy żądanie GET na adres: https://{{{host}}/api/org, z zachowaniem tego samego nagłówka Accept. Przed wysłaniem żądania przechodzimy jeszcze do zakładki Authorization i zmieniamy typ autoryzacji na Bearer Token, w polu token podajemy otrzymany uprzednio: {X-VMWARE-VCLOUD-ACCESS-TOKEN}}
7. Kliknij przycisk Send. W odpowiedzi powinniśmy otrzymać status 200 OK oraz listę wszystkich Organizacji, do których jesteśmy upoważnieni. Lista ta znajduje się w odpowiedzi, w sekcji Body.
Dzięki tak stworzonej metodzie autoryzacji możemy teraz dodawać kolejne żądania do naszej kolekcji bez konieczności uwierzytelniania każdego żądania w nagłówku, a poprzez ustawienie odpowiedniego tokenu w sekcji autoryzacji. Zatem, jedyne co należy zrobić, to zalogować się za pomocą połączenia POST. Po poprawnym uwierzytelnieniu będziemy mogli szybko i łatwo uruchamiać wszelkie żądania znajdujące się w kolekcji.
Portal Custom Branding – vCloud Director
Posiadając już kolekcję i skonfigurowaną metodę uwierzytelniania, postaramy się zmienić motyw portalu vCloud Director, który domyślnie prezentuje się następująco:
Interfejs użytkownika vCloud Director może być modyfikowany dla następujących elementów:
- Nazwa portalu
- Kolor portalu
- Motyw portalu (vCloud Director zawiera dwa tematy – domyślny i ciemny).
- Ikona Logo i przeglądarki
Wprowadzenie powyższych zmian nie jest zbyt skomplikowane i tylko nieznacznie zmienia graficzny interfejs użytkownika, dlatego postaramy się bardziej zagłębić w ten temat i stworzymy własny motyw.
Budowanie indywidualnego motywu będzie opierać się o generator motywów VCD UI Theme Generator. Dzięki niemu będziemy mogli stworzyć odpowiedni plik CSS, definiujący nasz nowy motyw. Nie będę omawiać procedury instalacji i posługiwania się wspomnianym generatorem. Wszelkie informacje na jego temat znaleźć można tutaj: https://github.com/vmware-samples/vcd-ext-samples/tree/theme-generator/10.1
Po wygenerowaniu motywu za pomocą generatora musimy wysłać odpowiednie żądania do API vCloud Director w celu umieszczenia nowego motywu.
- Krok pierwszy to tworzenie nowego motywu – pierwszą czynnością jaką należy wykonać jest stworzenie szablonu nowego motywu. Odbywa się to poprzez wystosowanie odpowiedniego żądania POST do API:
- POST: https://<vCD url>/cloudapi/branding/themes
- Przykładowe BODY:
{
"name": "Test", // nazwa motywu
"themeType": "Custom" //typ motywu
}
2. Tworzenie zawartości motywu – kolejny krok to tworzenie zawartości dla szablonu, jaki stworzyliśmy w kroku pierwszym. Operację tą przeprowadzamy za pomocą żądania POST.
- POST: https://<vCD url>/cloudapi/branding/themes//contents
- Przykładowe BODY:
{
"fileName": "testtheme.css", //nazwa stworzonego pliku css
"size": 447207 //rozmiar pliku css
}
W nagłówku zwrotnym tego żądania pojawi się link, który w następnych krokach zostanie użyty do umieszczenia pliku CSS. Przykładowa postać linku: <https://{vCD_FQDN}/transfer//testtheme.css>;rel=”upload:default”;type=”application/octet-stream”
3. Wysyłanie pliku CSS – na tym etapie następuje wysłanie wygenerowanego przez VCD UI Theme Generator pliku CSS. Aby przesłać własny plik CSS należy wystosować do API żądanie PUT.
- PUT: <https://{vCD_FQDN}/transfer//testtheme.css>;rel=”upload:default”;type=”application/octet-stream”
W nagłówku należy zdefiniować Content-Type i Content-Length (należy podać taką samą wartość, jaką zdefiniowaliśmy przy tworzeniu contentu. Jest to po prostu rozmiar pliku CSS podawany w bajtach). W body tego żądania zamieszczamy plik CSS.
4. Ostatnim krokiem jest aktywacja własnego motywu. By to zrobić należy wysłać żądanie PUT.
- PUT: https://<vCD url>/ cloudapi/branding/
- Przykładowe BODY:
{
"portalName": "My New Theme",
"portalColor": "#7e1414",
"selectedTheme": {
"themeType": "Custom",
"name": "Test"
}
}
Po wysłaniu żądania dotyczącego aktywacji motywu, powinniśmy otrzymać odpowiedź ze statusem 200 oraz – co naważniejsze – zobaczyć dokonane zmiany:
Wysyłając jakiekolwiek żądania warto również zwracać uwagę na statusy otrzymywanych odpowiedzi. Są to numeryczne, trzycyfrowe kody, które są dołączane do odpowiedzi i sygnalizują status odpowiedzi. Najczęstszymi statusami HTTP, z którymi możemy się spotkać są:
- 200 – OK, 201 – Created, 204 – No Content
- 400 – Złe zapytanie (Brakuje w zapytaniu wymaganych parametrów lub nie może być poprawnie odczytane)
- 401 – Niepowodzenie autoryzacji
- 403 – Dostęp zabroniony
- 404 – Nie znaleziono
- 405 – Niedozwolona metoda (Np. wysłanie pod dany adres metody POST, a nie GET)
- 500 – Błąd serwera
- 503 – Serwis niedostępny
Podsumowanie
Postman wydaje się być jednym z ciekawszych narzędzi do tworzenia i testowania API. Dzięki możliwości tworzenia kolekcji możemy w łatwy sposób przechowywać wszystkie żądania w jednym miejscu i korzystać z nich bez ograniczeń. Intuicyjny interfejs pozwala na sprawne odczytywanie i przeszukiwanie odpowiedzi (response) przetwarzanych żądań. Dodatkową opcją jest możliwość udostępniania swoich kolekcji innym użytkownikom, czy generowania dokumentacji w HTML. W aktualnej wersji programu możliwe jest także „mockowanie” serwerów oraz testowanie API, co czyni Postmana bardzo funkcjonalnym narzędziem do pracy przy tego typu projektach.
Pingback: Sterowanie pogodą, czyli jak zarządzać chmurami? » Inleo - Infrastruktura i architektura IT, Konteneryzacja, Datacenter, Private Cloud, PM