Wystawianie serwisów REST z aplikacji ABL cz.I

We wcześniejszych wpisach opisałem sposób tworzenia serwisów uruchamianych na serwerze aplikacji PAS (obecna nazwa to Application Server for OpenEdge), korzystających z danych strukturalnych JSDO.

Pora teraz na bardziej praktyczny przykład, opisujący wystawienie własnych serwisów REST ze zdefiniowaniem wystawianych zasobów i ich mapowaniem. W porównaniu do wcześniejszej metody będzie więcej czynności do wykonania ale dostaniemy znacznie większe pole manewru.

Na początek mamy projekt CustomerServ typu OpenEdge i prostą aplikację – klasę ABL Customer.cls z metodami dla zasobu Customer: ReadCustomer, ReadAllCustoomers, UpdateCustomer.

Ważne jest aby te metody były state-free, tzn. nie przekazywały kontekstu między wywołaniami.

Teraz prawy klik myszy na nazwie klasy Customer.cls -> Progress OpenEdge -> Define Service Interface.

Wybieramy Definition mode: REST i zaznaczamy wszystkie metody klasy, NEXT.

Do pliku klasy zostaną wstawione adnotacje. Nic tu nie zmieniamy. Finnish.

Widzimy, że pod Defined Services został zdefiniowany serwis CustomerServService oraz został dodany katalog PASOEContent dla serwera aplikacji.

Po prawej stronie otwiera się REST Resource URI Editor. Jeśli go nie ma to: prawy klik myszy Defined Service -> CustomerServService i wybieramy Edit.

Z operacjami na danych związane są tzw. czasowniki HTTP (HTTP verbs):

POST: operacja CREATE – tworzy nowy rekord

GET (domyślny): operacja RETRIEVE – zwraca rekord na bazie podanego ID

PUT: operacja UPDATE – aktualizuje istniejący rekord

DELETE: operacja DELETE – usuwa istniejący rekord.

Dodajemy 2 zasoby: /Customer (dla wszystkich rekordów Customer) oraz /Customer/{custNum}.

Dla zasobu /Customer kojarzymy verb GET z metodą ReadAllCustomers. Dla /Customer/{custNum} kojarzymy verb GET z metodą ReadCustomer, a PUT z UpdateCustomer.

Teraz trzeba zmapować parametry dla każdej operacji pomiędzy parametrami wejścia HTTP request a parametrami wejścia ABL oraz parametrami wyjścia ABL a parametrami HTTP response.

Najpierw mapujemy operacje dla ReadAllCustomers GET: input Complete URL w HTTP Request do URI  w Interface Parameters; Query String Parameters w HTTP Request do num w Interface Parameters.
Teraz output: ttAllCustomers w Interface Parameters do Body w HTTP Response.

Dla ReadCustomer GET mapujemy: input – Path Parameters custNum w HTTP Request do custNum w Interface Parameters.
Output: CustomerRecord w Interface Parameters do Body w HTTP Response.

Na koniec dla UpdateCustomer PUT mapujemy: input – Path Parameters custNum w HTTP Request do custNum w Interface Parameters oraz Body w HTTP Request do CustomerRecord w Interface Parameters.
Output: CustomerRecord w Interface Parameters do Body w HTTP Response.

Zakończyliśmy definiowanie serwisu REST.