Nieuws

10 min leestijd

REST API met Magento 2

Op 2 oktober was ik op het tweede Yireo Magento 2 Seminar in Utrecht (Nederland). Er was een kort gesprek over "API's in Magento 2" gepresenteerd door Andra Lungu, Magento ontwikkelaar bij BitBull_IT.

Op dit moment bouwen we een zeer grote Magento 2 winkel voor een van onze klanten. Voor dit project moeten we integreren met verschillende externe systemen/platforms. Bijvoorbeeld: we moeten tijdens de orderstroom regelmatig orderinformatie naar hun CRM sturen. Om een PDF van de order / factuur te maken, hebben we het relatienummer van de klant nodig om af te drukken in de header van het document. Omdat het relatienummer niet in Magento is opgeslagen moeten we een REST API opzetten om dit nummer uit CRM op te halen.

Ik zal u een algemeen overzicht geven hoe u uw eigen web API met Magento 2 kunt bouwen op basis van code voorbeelden.

Protocollen en authenticatie

Magento 2 ondersteunt SOAP en REST met authenticatietypes op basis van OAuth, Token en Session. De request body voor REST kan JSON of XML zijn (gebruik de juiste Content-Type header: application/json of application/xml).

Voor nu laat ik u zien hoe u kunt beginnen met Token Based Authenticatie. Om een admin token te krijgen kun je gebruik maken van het V1/integratie/admin/token API eindpunt.

Een succesvol verzoek stuurt een antwoordapparaat terug met het token, als volgt: 45462b4c4c237b57e4gxbfke10epwm87w9

Voor de meeste web API-oproepen levert u dit token in de autorisatieaanvraag-header met het HTTP-autorisatieschema voor dragers om uw identiteit te bewijzen. Het token vervalt nooit, maar kan worden ingetrokken.

  • Zorg ervoor dat de gebruiker bestaat en toegang heeft tot minstens één bron/rol.
  • De tokens worden opgeslagen in de database in de oauth_token tabel.
Protocols and authentication
Authorization-access the resources_roles

Autorisatie: toegang tot de middelen/rollen

Alle accounts (Token-based) en integraties (OAuth-based) zijn toegewezen aan resources/rollen waartoe ze toegang hebben. De API-module van Magento 2 controleert of elke aanroep toestemming heeft om het verzoek uit te voeren. Bijvoorbeeld: als ze geautoriseerd zijn voor de Magento_Sales::sales resource, kunnen ze een GET /V1/orders/:id call maken. De middelen worden gedefinieerd in acl.xml.

In ons project definiëren we een nieuwe resource/rol in app/code/Phpro/Sales/etc/acl.xml.

Configureer een web API eindpunt

Om een web API voor een dienst te configureren, definieert u XML-elementen en attributen in een webapi.xml configuratiebestand.

In ons project definiëren we de web API dienst in app/code/Phpro/Sales/etc/webapi.xml.

Magento maakt de service methode dynamisch beschikbaar via de web API. Het is erg belangrijk dat de serviceklasse op een zeer specifieke manier is geformatteerd. Magento gebruikt reflectie om automatisch deze PHP-klassen te creëren en zet de ingediende JSON of XML om in overeenkomstige methode argumenten. Omgekeerd, als een object wordt geretourneerd van een van deze methoden, zet Magento het object ook om in een JSON- of XML-antwoord. Om deze conversie te doen, moeten alle methoden blootgesteld door de web API volgen deze regels:

  • Parameters moeten in het doc-blok worden gedefinieerd als * @param type $paramName
  • Aangiftetype moet in het doc-blok worden gedefinieerd als * @ retourtype
  • Geldige scalar types: boolean (bool), string (str), integer (int), float en double.
  • Geldige objecttypes omvatten een volledig gekwalificeerde klassenaam of een volledig gekwalificeerde interface-naam
  • Elke parameter of retourwaarde van een type-array kan worden aangegeven door een van de voorgaande typen te volgen met een lege set vierkante haakjes []. Bijvoorbeeld * @param string[] $types
  • Optionele request paramaters kunnen als volgt worden ingesteld: public function methodName($arg1, $arg2 = 0, $arg3 = null);

In \Magento\Webapi\Controller\Rest\InputParamsResolver::resolve() zie je de logica die verantwoordelijk is voor de verwerking en het oplossen van de invoerparameters, zichtbaar is.

Configure a web API endpoint
Phpro_Sales web API module

De web API module

Links de structuur van de Phpro_Sales web API module.

Registratie van de module

app/code/Phrpo/Sales/registration.php

Registration of the module_1
Registration of the module_2

app/code/Phrpo/Sales/etc/module.xml

app/code/Phrpo/Sales/Setup/InstallSchema.php

Registration of the module_3
Configure the web API_1

Configureer de web API

Zie hierboven app/code/Phpro/Sales/etc/webapi.xml en app/code/Phpro/Sales/etc/acl.xml.

Maak een nieuwe interface: app/code/Phpro/Sales/Api/RestOrderManagementInterface.php

Definieer de implementatie van de methode: app/code/Phpro/Sales/Model/RestOrderManagement.php

Configure the web API_2
Configure the web API_3

Vergeet niet een voorkeur in te stellen voor de interface in app/code/Phpro/Sales/etc/etc/di.xml

Run bin/magento setup:upgrade en bin/magento cache:flush om de Phpro_Sales module te registreren en in te schakelen.

Testen van de web API

Om de web API te valideren kunt u een POST verzoek met krul of een REST client zoals Postman sturen.

Zorg ervoor dat het token in de Autorisatie header staat en het relatieNummer in de body van het verzoek.

Een succesvol verzoek geeft een HTTP 200-status en een respons body "true". Ook het relatienummer moet worden opgeslagen of bijgewerkt in de sales_order tabel (als de order bestaat).

Tot slot is het heel eenvoudig om een basis REST of SOAP API met Magento 2 op te zetten om bijvoorbeeld te integreren met externe systemen: CRM of ERP.

testing the web API