Data Ingestion REST API playground (staging)

[jeff-matthews]

Purpose of this pull request

This pull request (PR) implements the GetCredential component for the Catalog Data Ingestion REST API. It enables Redocly's integrated API client in the reference documentation (relates to commerce-webapi#462).

Staging

https://developer-stage.adobe.com/commerce/services/reference/rest/

TODOs

• Consult with PM/ENG to ensure alignment/expectations
• Create project template for ACO in Adobe Developer Console (or add ACO API to existing template)
• Replace templateId in get credential component (maybe; see previous TODO)
• Add guidance for manually adding tenantId (get credentials component currently doesn't support retrieval)
• Address OpenAPI spec errors (e.g., add x-summary to long response objects to fix page overflow on render)
• Remove unnecessary Redocly config file
• Deploy to staging for testing
• Replace stage template ID & server URL with production (sandbox) as final step
  • We'll do this in the delivery to main. I created a new integration branch for this PR because it got a little messy.

[jeff-matthews]

I'm not sure why, but the Try it console is displaying the server description instead of the url:

I don't know if this is a bug or expected behavior, but we need to show the URL here, even if that means removing the description.

[jeff-matthews]

Another thing to note that isn't very intuitive: the Security section in the Try it console provides a dropdown menu that you must select for each of the three fields required to complete the request (e.g., API key, bearer token, and IMs org).

This might be why the AEP team chose not to use the securitySchemes OpenAPI object and used parameters instead. Parameters show as a flat list and don't require clicking through dropdown menus.

If we can't control the display of the Try it console, is it worth not adhering to the OpenAPI spec to improve UX?

[meker12]

Another thing to note that isn't very intuitive: the Security section in the Try it console provides a dropdown menu that you must select for each of the three fields required to complete the request (e.g., API key, bearer token, and IMs org).

This might be why the AEP team chose not to use the `securitySchemes` OpenAPI object and used parameters instead. Parameters show as a flat list and don't require clicking through dropdown menus. If we can't control the display of the **Try it** console, is it worth not adhering to the OpenAPI spec to improve UX?

In my opinion yes --

[meker12]

I'm not sure why, but the Try it console is displaying the server description instead of the url:

I don't know if this is a bug or expected behavior, but we need to show the URL here, even if that means removing the description.

I notice that the description is not provided in any of the Target API specs. Another example of not following the spec to support better usability of the component, but it does seem like you should be able to have both.

[jeff-matthews]

@meker12

I create an integration branch and updated the base branch for this PR accordingly. I think that this Pr should be for our review. When we merge with the integration branch, I'll create a new PR for developer review.

[meker12]

Not sure if it works, but I think it makes more sense to include the instructions for adding the tenant ID info with the access token.

[jeff-matthews]

See #284 for draft production PR.