adobedocs / commerce-webapi

Source code for Adobe Commerce Web APIs developer documentation

Adobe Commerce Developer Documentation

Welcome! This site contains the latest Adobe Commerce and Magento Open Source developer documentation for ongoing releases of both products. For additional information, see our Contribution Guide.

Contributors

Our goal is to provide the Adobe Commerce and Magento Open Source communities with comprehensive and quality technical documentation. We believe that to accomplish that goal we need experts from the community to share their knowledge with us and each other. We are thankful to all of our contributors for improving the documentation.

Local development

This is a Gatsby project that uses the Adobe I/O Theme. Ensure that your local environment matches the prerequisites described in the Adobe I/O Theme README.

To build the site locally:

1. Clone this repo.

2. Install project dependencies.

   yarn install

3. Launch the project in development mode.

   yarn dev

Resources

See the following resources to learn more about using the theme:

• Arranging content structure
• Linking to pages
• Using assets
• Configuring global navigation
• Configuring side navigation
• Using content blocks
• Writing enhanced Markdown
• Deploying the site (Adobe employees only)

If you have questions, open an issue and ask us. We look forward to hearing from you!

GraphQL API reference generator

The GraphQL API reference is generated using an open-source tool SpectaQL. The data required for the generator is located at the spectaql directory:

• adobe-theme: custom theme.
• config.yml: configuration file.
• schema.json: the GraphQL schema extracted from the Adobe Commerce (B2B) instance.

The resulted GraphQL API reference lives in the static/graphql-api/ directory. It is embedded into the /graphql/reference page using the frameSrc feature on the DevSite.

To rebuild the GraphQL API reference after any updates, run:

yarn build:spectaql

To run SpectaQL in the development mode:

yarn dev:spectaql

How to get the schema

The website in the public directory was generated for the Adobe Commerce with B2B instance from GraphQL Schema 'schema.json'. The schema was retrieved using the apollo-cli tool:

npx apollo-cli download-schema $ENDPOINT_URL --output schema.json

where $ENDPOINT_URL is a placeholder for a URL's endpoint.

For more information about SpectaQL, refer to https://github.com/anvilco/spectaql.

commerce-webapi's Issues

Duplicate `product_sale_price` property request in customer orders query

Expected Behaviour

The docs snippet for the customer orders graphQL query should have a single entry for the product_sale_price property

Actual Behaviour

There's docs include a duplicate entry, effectively requesting the property twice

Reproduce Scenario (including but not limited to)

Steps to Reproduce

Just head to https://developer.adobe.com/commerce/webapi/graphql/schema/customer/queries/customer/ and read the snippet

Platform and Version

Magento 2.4

Sample Code that illustrates the problem

{
  customer {
    orders(filter: {number: {eq: "000000001"}}) {
      total_count
      items {
        id
        number
        order_date
        status
        items {
          product_name
          product_sku
          product_url_key
          product_sale_price {
            value
          }
          product_sale_price {
            value
            currency
          }
...

Logs taken while reproducing problem

Redocly REST API Schema Cannot be Downloaded

Expected Behaviour

I should be able to download the schema.json file(s) from https://magento.redoc.ly/. Ideally, I should be able to download the individual schema.json files or a unified schema.json file that contains all three schema definitions.

Actual Behaviour

There are no schema download links at

• https://magento.redoc.ly/2.4.5-admin/
• https://magento.redoc.ly/2.4.5-customer/
• https://magento.redoc.ly/2.4.5-guest/

Issue in /src/pages/rest/tutorials/bundle-product/create-simple-products.md

There appears to be an empty info box at the bottom of the page.

Pulling Magento 2 OpenAPI spec version 2.4.6 seems to contain an error

Is there an existing issue for this?

• I have searched the existing issues

Which topic?

https://developer.adobe.com/commerce/webapi/rest/quick-reference/

What's wrong with the content?

Current and previous versions of the OpenAPI specification have multiple errors.
Many nullable fields are not marked as nullable.
But the biggest problem is:
Open the swagger.json with Swagger Online Editor

What changes do you propose?

Correct the spec

Anything else that can help to cover this?

No response

Source not mentionned in request

Issue in /src/pages/rest/tutorials/orders/order-create-shipment.md

When using MSI in Magento 2.4.X the request as stated in the doc results in an error in exception.log :

The shipment couldn't be saved. {"exception":"[object] (Magento\Framework\Exception\CouldNotSaveException(code: 0): The shipment couldn't be saved. at /vendor/magento/module-sales/Model/Order/ShipmentRepository.php:150, Magento\Framework\Exception\LocalizedException(code: 0): Not all of your products are available in the requested quantity. at /vendor/magento/module-inventory-source-deduction-api/Model/SourceDeductionService.php:86)"} []

If the shipment is done through the backend though it is working.

To make it work from the rest API we need to specify the source to decrease the quantity from, just as in the backend using this bit of json :

"arguments": {
   "extension_attributes" : {
         "source_code" : "SOURCE_CODE"
    }
},

A working example would then be :

{
   "items":
    [
        {"order_item_id":6902,"qty":1}
    ],
    "arguments": {
        "extension_attributes" : {
            "source_code" : "DEP"
        }
    },
    "notify": false
}

This seems to be mandatory and should be stated in the documentation

Host missing

Is there an existing issue for this?

• I have searched the existing issues

What's missing?

In the https://developer.adobe.com/commerce/webapi/get-started/authentication/gs-authentication-token/
Its missing or unclear what the host should be or how you can find it in your Magento.
I tried using magento.host/index.php but that just gives me a 405 Not Allowed Error so no I'm completely stuck because I don't have my correct

REST API Documentation is radically different between Redocly and Local

Expected Behaviour

I should see the same endpoints described at http://<host>/swagger (in some way) as I see at https://magento.redoc.ly, even though the generated shape will be different because of the difference between Swagger and ReDoc.

Actual Behaviour

The documentation for generating a local Schema reference provides the /swagger URL which, if the store is not in production mode, should work and provide useful schema documentation. However, the schema (http://<host>/rest/all/schema?services=all) and Swagger UI appear to have an entirely *different* set of generated UI and API descriptions than that provided via https://magento.redoc.ly (ignoring the different generators; from my local instance, I cannot find the admin API /V1/customers/search, but only /V1/search`, in the Swagger UI).

This would be unnecessary if the various JSON schema files could be downloaded from https://magento.redoc.ly, as described in #41.

Looks like the Commerce Web APIs Rest Attributes page UI is broken

Issue in /src/pages/rest/attributes.md

Wrong redirect link to updateCustomerV2 mutation

Issue in /src/pages/graphql/schema/customer/mutations/update.md

I noticed that when I open this page and I click on "updateCustomerV2 mutation" link I'm being redirected to "create-v2" page instead of "update-v2".

Issue in /src/pages/rest/tutorials/bundle-product/create-bundle-product.md

Found a typo in the payload, should be computer-ram. it wont affect anything, since its a sku, but it looks funny being misspelled.

"sku": "compuer-ram"

"GraphQL functional testing" URL is broken

Issue in /src/pages/get-started/web-api-functional-testing.md

GraphQL functional testing.

This URL leads to 404 error.

Create an integration page is outdated.

Is there an existing issue for this?

• I have searched the existing issues

Which topic?

https://developer.adobe.com/commerce/webapi/get-started/create-integration/#define-the-required-resources

What's wrong with the content?

In step 5 of the guide, the example shows to use Magento\Framework\Setup\InstallDataInterface when creating an integration. However, the code sniffer + technical reviews of the extension throws the error: InstallData scripts are obsolete. Please use data patches approach in module's Setup/Patch/Data dir

What changes do you propose?

Update the article with working examples

Anything else that can help to cover this?

No response