Magento 2: Wstęp do REST API

0

Z racji tego, że istnieje potrzeba udostępniania systemu i jego danych innym systemom zewnętrznym, Magento oferuje różnego rodzaju API, które implementuje większość podstawowych funkcji. Magento 2 dostarcza nam REST API i SOAP — oba obsługiwane są przez to same klasy.

Co to jest REST API?

Magento 2 REST API udostępnia różne funkcje, które pozwalają na wykonanie żądań i otrzymania odpowiedzi. Pomimo że sam w sobie REST jest stylem architektonicznym i teoretycznie nie jest zależny od protokołu. W praktyce jednak interakcja odbywa się przez protokół HTTP.

Klient wysyła żądanie HTTP, które zawiera poniższe elementy:

  • Nagłówek HTTP, który dostarcza nie tylko dane uwierzytelniające, ale także inne instrukcje,
  • Typ żądania kierowany do endpointa, może to być GET, POST, PUT lub DELETE,
  • Endpoint jest to ujednolicony identyfikator zasobów (ang. URI — Uniform Resource Identifier),
  • Wywołanie bloki danych (ang. payload) zawiera zestaw parametrów wejściowych i atrybutów, które są dostarczane wraz z żądaniem.

Blok danych oraz status HTTP zostanie zwrócony w odpowiedzi.

Nagłówki HTTP

NagłówekSkładniaOpis
Authorization
(wymagany)		Authorization: Bearer <token>Określa token uwierzytelniający, który potwierdza, że jesteś uprawionym użytkownikiem Magento. Potrzebujemy w nagłówku żądania określić za pomocą bearer tokena.
Accept
(opcjonalny)		Accept: application/jsonOkreśla format odpowiedzi JSON lub XML, domyślny format to JSON.
Content-Type
(Wymagany, gdy przez żądanie wysyłamy dane)		Content-Type: application/jsonOkreśla format przysyłanych danych: JSON lub XML.
REST API potrzebne nagłówki

HTTP verb

  • GET — pobieranie docelowego zasobu przez podanie jego identyfikatora,
  • POST — tworzy nowy zasób, umożliwia pobieranie danych w ramach dostarczenia danych w treści żądania, używany jeśli inne operacje nie pasują do użytku,
  • PUT — aktualizuje nowy zasób. Może też być wykorzystywana do tworzenia nowego zasobu jeśli znany jest jej identyfikator. Żądanie utworzenia stanu zasobu docelowego lub zastąpienia go stanem, który jest zdefiniowany przez zawartą w bloku wiadomości żądania,
  • DELETE — żądanie, które obsługuje usuwanie określonego zasobu przez identyfikator,
  • PATCH — żądanie, które aktualizuje część wskazanego zasobu (i ta część właśnie odróżnia go od żądania typu PUT). Adapter Magento nie wspiera w tym momencie metody PATCH — mamy tu wątek na github, gdzie mamy informację o tym, że musimy rozszerzyć klasę Magento\Framework\HTTP\Adapter\Curl od obsługi takiego rodzaju żądania i użyć jej we własnym kodzie.

Obsługiwane formaty

REST API obsługuje następujące formaty:

Endpoint

Punkt końcowy, który bardzo często nazywany jest endpointem, określa dostęp do zasobu. Najczęściej adres usługi ma następującą strukturę:

http://<adres-serwera>:<port-aplikacji>/<endpoint>

Jeśli chodzi o Magento 2 dostęp do przykładowego zasobu:

https://shop-page.local/rest/<store_code>/V1/cmsPage/{id}

  • rest — ścieżka określająca typ serwisu, tutaj REST API,
  • <store_code>— kod store przypisany do sklepu, domyślnie jest to default,
  • /V1/cmsPage — jest zasobem, do którego chcemy uzyskać dostęp,
  • {id} – id zasobu, dla wspomnianego endpointa jest to argument szablonowy.

Kod sklepu może przyjmować następujące wartości:

  • kod sklepu – przypisany do strony sklepu. Kod sklepu jest przechowywany w tabeli store w kolumnie code. Domyślnie mamy dwa kody: admin i default.
  • default — wartość domyślna gdzie kod sklepu nie jest wprowadzony,
  • all — tylko dla enpointów dla modułów związanych ze stronami CMS i produktami. Takie żądanie API będzie miała efekt na wszystkie sklepy.

Listę poszczególnych endpointów znajdziesz na stronie https://developer.adobe.com/commerce/webapi/rest/quick-reference

Rodzaje tokenów w Magento 2

W zależności jaki rodzaj tokena potrzebujemy uzyskać, wybieramy odpowiedni endpoint:

Typ tokenaOdpytanieCzas
Ważności
(godziny)
AdminPOST V1/integration/admin/token4
Admin
z Google Authenticator		POST /V1/tfa/provider/google/authenticate4
Admin z Duo SecurityPOST /V1/tfa/provider/duo-security/authenticate4
Admin z AuthyPOST /V1/tfa/provider/authy/authenticate4
Admin z U2FPOST /V1/tfa/provider/u2fkey/verify4
Customer (self lub anonymous)POST /V1/integration/customer/token1
IntegrationRequest token (tymczasowy token):
POST /oauth/token/request
który wymieniamy na access token:
POST /oauth/token/access
Jak wykonać odpytanie znajdziesz informację tutaj.		Nieokreślony
Rodzaje tokenów i dostępnych endpointów do ich generowania

W zależności od typu użytkownika, wygenerowany token, który daje nam konkretne dostępy. Użytkownik Guest, nie ma ustawionego tokena.

Konfiguracja endpointa i dostępów do niego w module

Definicja poszczególnych endpointów znajdziemy w pliku konfiguracyjnym webapi.xml, który jest umieszczony w folderze etc danego modułu. Plik zawiera definicję ścieżki route wraz z całą konfiguracją dotyczącą endpointa ścieżki, zasobu, parametrów itd.

Poniżej przykładowa definicja endpointa z modułu Magento_Checkout. Mamy endpoint, który obsługuje obliczanie sum dla zamówienia:

    W zależności od typu użytkownika, mamy inny endpoint, lecz także określony inny rodzaj dostępu do zasobu:

    • Magento_Cart::manage – dla administratora, który powinien mieć przypisany dostęp do zasobu w konfiguracji. Jest to reguła ACL, której konfiguracja znajduję się w pliku etc/acl.xml modułu,
    • self – odnosi się do zasobu, do którego ma dostęp obecny, zalogowany użytkownik,
    • anonymous – takie endpointy odnoszą się do anonimowego użytkownika. Użytkownik, gość, to taki użytkownik, który nie został zautoryzowany poprzez ustawienie tokena.

    Elementy konfiguracyjne webapi.xml:

    • Węzeł <route> (wymagany), który posiada następujące atrybuty:
      • method (wymagany) – nazwa metody HTTP, dozwolone wartości to: GET, POST, PUT i DELETE,
      • url (wymagany) – url do zasobu, w stylu /V1/products/:sku, gdzie :sku jest parametrem do podstawienia,
      • secure (opcjonalny) – true/false, określa czy podana ścieżka jest dostępna tylko przez https,
      • soapOperation (opcjonalny) – do określenia nazwy operacji dla SOAP, która jest inna niż nazwa metody interfejsu. Ustawiamy, gdy potrzebujemy określić wiele operacji dla tego samego kontraktu serwisowego.
    • Węzeł <service> (wymagany), element potomny węzła <route>. Posiada atrybuty:
      • class (wymagany) – interfejs klasy,
      • method (wymagany) – nazwa metody do wykonania.
    • Węzeł <resources> (wymagany), stanowi element potomny węzła <route>. Jest to kontener dla konfiguracji dostępu,
    • Węzeł <resource> (wymagany), element potomny węzła <resources>. Posiada atrybut:
      • ref (wymagany) – jako referencja do wartości określającej rodzaj dostępu do zasobu. Dozwolone wartości to self, anonymous lub nazwa reguły ACL na przykład Magento_Cart::manage.
    • Węzeł <data> (opcjonalny), element potomny węzła <route>. Jest kontenerem dla jednego lub wiele definicji parametrów,
    • Węzeł <parameter> (wymagany, gdy węzeł <data> jest określony), element potomny węzła <data>:
      • name – nazwa parametru,
      • force – true/false. Daje pewność, że dana wartość będzie wymuszona. W przykładzie dla definicji dostępu z self mamy określony parametr cartId, który musi odpowiadać identyfikatorowi koszyka obecnie zalogowanego użytkownika.

Konfiguracja roli dla REST API

Do stworzenia roli w Magento 2 potrzebujemy zalogować się do admina, gdzie z menu wchodzimy System ⮞ User Roles.

Klikamy na przycisk Add New Role. W pierwszej zakładce formularza wpisujemy nazwę roli oraz hasło obecnie zalogowanego konta.

Następnym krokiem jest określenie zasobów, dla których dodana rola będzie miała dostęp. Dla ustawienia Resource Access mamy dwie opcje do wyboru:

  • All,
  • Custom.

Opcja Custom pozwala nam na wybranie konkretnych zasobów dla tworzonej roli użytkownika:

Stworzoną rolę możemy teraz przypisać wybranemu użytkownikowi.

Aby stworzyć użytkownika lub przypisać nową rolę istniejącemu użytkownikowi, potrzebujemy wejść w menu System ⮞ All Users.

W formularzu edycji, w zakładce User Role wybieramy interesującą nas rolę do przypisania.

Ustawienie roli dla użytkownika

Wykonanie zapytania do Magento 2 REST API

Wykonajmy teraz zapytanie REST API do Magento 2. Do wykonania zapytań możesz użyć narzędzia POSTMAN, stworzyć zapytania za pomocą CURL-a, a następnie je zaimportować.

Przykłady, które przedstawie w dalszej części, możesz łatwo zaimportować do POSTMAN-a.

Uwierzytelnienie użytkownika

Pierwszą rzeczą jest odpytanie endpointa o token, aby na podstawie danych naszego konta użytkownika wygenerować token, który pozwoli uzyskać dostęp do uprawnionych zasobów. W zależności od typu tokena potrzebujemy odpytać inny endpoint.

Odpytanie o token bez włączonego 2FA wykonujemy za pomocą integration/admin/token:

W przypadku, gdy mamy włączone 2FA, od Googla, potrzebujemy wykorzystać endpoint: tfa/provider/google/authenticate.

W przykładzie parametr otp jest tymczasowym, 6-cyfrowym hasłem, które musimy przepisać w używanej przez na aplikacji na przykład z Authy.

Przykładowa odpowiedź zwraca token:

Przykładowe odpytanie o stronę CMS

Wygenerowany token możemy następnie użyć przy zapytaniu o dostępne zasoby. Wypytajmy Magento o zwrócenie informacji na temat konkretnej strony CMS.

W celu wykonania zapytania jako użytkownik admin potrzebujemy do zapytania określić nagłówek Authorization i ustawić mu wygenrowany token. W CURL-u odpowiada za to opcja -H:

Magento 2 zwraca nam odpowiedź: