Magento 2 – Understanding Web API Integration

apiintegrationmagento2

Per the developer documentation

Integration style web API’s enable a single web API call to run multiple services at once for a more efficient integration. An example of this behavior can be see in the Catalog where one web API call can create a product; if your payload includes the inventory object and media object then the framework will also create the product’s inventory & media in that one API call.

Create a new integration on Magento Admin. To create an integration, click System > Integration > Add New Integration. Be sure to restrict which resources the integration can access.

It's not all that clear what, exactly, an integration is. The first documentation snippet indicates an integration is (maybe?) a way to chain multiple API calls in a single HTTP request. However, there's no syntax example of this. Also, if I use the information in the second documentation snippet I can create an integration object, but it's not clear what I'm supposed to do with this. Also, digging into the code, integration objects appear to use a different authentication code path.

Does anyone have a clear idea what these "API Integrations" are, and how they work?

Best Answer

There are 4 types of users in Magento 2 (see \Magento\Authorization\Model\UserContextInterface), any of them can be used while making requests via web APIs :

  • Anonymous users (guests). User is considered to be anonymous if no tokens or cookies were used to make requests
  • Customers. Customer token or cookie must be passed along with request
  • Admins. Admin token or cookie must be present
  • Integrations. Integration access token should be passed in OAuth 2.0 style OR request should be properly signed using consumer key, consumer secret, access token, access token secret in OAuth 1.0a style

Integration can be created at System > Integration > Add New Integration, it can be given the same permissions as any Admin user (ACL tree is the same). Web API requests can be made on behalf of both, admin and integration. What differs integration from the admin user is that 3rd party can retrieve web API credentials using OAuth handshake.

OAuth handshake allows to integrate with multi-user 3rd party system automatically (when supported by 3rd party):

  • During integration creation fill out optional fields Callback URL and Identity Link URL (both should be provided by 3rd party system)
  • When you try to activate integration, OAuth handshake will be triggered
  • Some data will be sent by Magento to Callback URL using server-to-server POST request. Identity Link Url (login page on 3rd party system) will be opened in popup window and some GET parameters will be sent
  • After successfully authenticated user credentials, 3rd party will request Request Token from Magento and then exchange it for Access token. It will also associate current Magento instance with user account on its own records. I.e. multiple Magento merchants can have accounts in the same 3rd party CRM, and every merchant's account will be tied to his Magento instance
  • Issued access token can be used to make requests to Magento web API. This token will be associated with Magento Integration record and will have access to resources selected in API tab of Integration edit page

Quick note about calling multiple services at once, this feature is better known as aggregation APIs and does not have anything in common with Integration user type.