Incorrect Description of an Integration API

[astorm]

On

http://devdocs.magento.com/guides/v2.0/get-started/bk-get-started-api.html

Contains this text

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.

However, according to Alex Paliarush

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.

So it seems like the above information in incorrect.

At minimum, this should be fixed.

Ideally, a section description how an "integration" user works should be added, and a section on using aggregated APIs should be added.

[tanberry]

Thanks, @astorm , absolutely right and we will get that fixed. So it sounds like we need to separate the concepts: calling multiple services at once (known as "Aggregat[ing?] APIs"), and the other concept of using an Integration User type. Does that sound right to you?

Lucky for us Alex Paliarush moved to Austin, and sits right across from @keharper, our API writer. Thanks again, Alan!

[astorm]

So it sounds like we need to separate the concepts: calling multiple services at once (known as "Aggregat[ing?] APIs"), and the other concept of using an Integration User type. Does that sound right to you?

Yup.

Also, Re: Integrations -- this could benefits from a full user story style treatment. i.e. Integrations (seem to be?) intended as a way to allow a third party service access to the Magento API via oAuth credentials instead of via a username and password. More information is needed on

1. The complete user flow from a merchant point of view
2. The complete steps a developer working for the third party company would take to setup the oAuth endpoints and receive their Magento credentials

This page probably contains the information needed, but it's very confusing as to what a third party developer needs to implement.

Probably a great place to provide

1. A module that adds a sample integration with the two URL endpoints configured
2. Simple PHP example code to implement the two URLs from Sample #1's integration

[tanberry]

Great feedback, thanks. Yes, we want to add more workflows, step-by-step, even tutorials on using our APIs, Integrations, Service contracts, etc. Both of the two you name are needed, agreed.

On your suggestion about adding a module that has a sample integration... do you mean Magento creating an out-of-box that is part of core, or perhaps a sample module in our repo?

[astorm]

@tanberry a sample module in our repo, or my usual approach of walking someone step by step through a "here's how'd you create this". This wouldn't be something that exists in Magento's core.

[tanberry]

Got it, thanks @astorm ! Yes, we need more of your approach with the "here's how."

[keharper]

This was documented long ago, but not closed out.

Create an integration: http://devdocs.magento.com/guides/v2.1/howdoi/webapi/integration.html

OAuth-based authentication: http://devdocs.magento.com/guides/v2.1/get-started/authentication/gs-authentication-oauth.html