What is a Magento 2 "Web API Integration"

Question

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?

Answer 1

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.

Answer 2

The integration here is the scenario that integrators and developers the means to use web services that communicate with the Magento system via Magento API. They can call one or many services that Magento allow that the admin configure in New Integration Form (Scroll down in that screen to select specific API or select all)

Because of security problem, The Magento just permits external authorized requests via one of three types authentications: - Token-based authentication - OAuth-based authentication - Session-based authentication

With any type of authentication, the integrator and developer must have an user account register with the Magento. With user account, you can get token Id which you need to send with your request to the Magento.

For example, I suppose you already have user account and integration info. Now you're going to request to get token from the Magento. I show you the snippet using the first type of authentication (Token-based authentication):

curl -X POST "https://localhost/magento/index.php/rest/V1/integration/admin/token" \
     -H "Content-Type:application/json" \
     -d '{"username":"user_example", "password":"123123q"}'

If successful, you get a token like "asdf3hjklp5iuytre"

Now you can integration with the Magento to request data by calling its API

curl -X GET "http://localhost/magento/index.php/rest/V1/customers/2" \
     -H "Authorization: Bearer asdf3hjklp5iuytre"

Finally, you may receive a list of customers from the Magento. I'm using the curl command for example, the integrator and developer may implement by PHP, C# or another language to create an web service request to a service url.

PS: SoapUI is useful tool to make service request for testing.

Hope this helps.