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ć.

• 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

https://evoila.com/blog/terraform-i-vcloud-director/

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ć.

1. 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.

1. 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.