Magento 2: Wstęp do REST API

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

HTTP verb – czyli rodzaje obsługiwanych żądań

• 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:

• JSON — JavaScript Object Notation,
• XML — Extensible Markup Language.

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:

W zależności od typu użytkownika, wygenerowany token pozwala uzyskać konkretne dostępy. W przypadku użytkownika Guest – token nie jest używany.

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:

<?xml version="1.0"?> <!-- /** * Copyright © Magento, Inc. All rights reserved. * See COPYING.txt for license details. */ --> <routes xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Webapi:etc/webapi.xsd"> <!-- (...) --> <!-- Managing totals information --> <route url="/V1/carts/:cartId/totals-information" method="POST"> <service class="Magento\Checkout\Api\TotalsInformationManagementInterface" method="calculate"/> <resources> <resource ref="Magento_Cart::manage" /> </resources> </route> <!-- Managing guest totals information --> <route url="/V1/guest-carts/:cartId/totals-information" method="POST"> <service class="Magento\Checkout\Api\GuestTotalsInformationManagementInterface" method="calculate"/> <resources> <resource ref="anonymous" /> </resources> </route> <!-- Managing My totals information --> <route url="/V1/carts/mine/totals-information" method="POST"> <service class="Magento\Checkout\Api\TotalsInformationManagementInterface" method="calculate"/> <resources> <resource ref="self" /> </resources> <data> <parameter name="cartId" force="true">%cart_id%</parameter> </data> </route> <!-- (...) --> </routes>

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38

<?xml version="1.0"?> <!-- /** * Copyright © Magento, Inc. All rights reserved. * See COPYING.txt for license details. */ --> <routes xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"         xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Webapi:etc/webapi.xsd">     <!-- (...) -->     <!-- Managing totals information -->     <route url="/V1/carts/:cartId/totals-information" method="POST">         <service class="Magento\Checkout\Api\TotalsInformationManagementInterface" method="calculate"/>         <resources>             <resource ref="Magento_Cart::manage" />         </resources>     </route>       <!-- Managing guest totals information -->     <route url="/V1/guest-carts/:cartId/totals-information" method="POST">         <service class="Magento\Checkout\Api\GuestTotalsInformationManagementInterface" method="calculate"/>         <resources>             <resource ref="anonymous" />         </resources>     </route>       <!-- Managing My totals information -->     <route url="/V1/carts/mine/totals-information" method="POST">         <service class="Magento\Checkout\Api\TotalsInformationManagementInterface" method="calculate"/>         <resources>             <resource ref="self" />         </resources>         <data>             <parameter name="cartId" force="true">%cart_id%</parameter>         </data>     </route> <!-- (...) --> </routes>

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:
• Węzeł <service> (wymagany), element potomny węzła <route>. Posiada atrybuty:
• 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:
• 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>:

Konfiguracja roli dla REST API

Cały proces konfiguracji, utworzenie roli oraz przypisanie jej do użytkownika zostało przedstawione w tym wpisie.

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:

eyJraWQiOiIxIiwiYWxnIjoiSFMyNTYifQ.eyJ1aWQiOjIsInV0eXBpZCI6MiwiaWF0IjoxNzAzODk5MDU1LCJleHAiOjE3MDM5MDI2NTV9.nV1RF_0C-kMRwSxGn3msXoOqBZbKqM5bKYN1d21AIKY

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 wygenerowany token. W CURL-u odpowiada za to opcja -H:

Odpowiedź Magento 2 na powyższe zapytanie: