Services for Adobe Commerce Documentation

Welcome! This site contains the latest Services for Adobe Commerce developer documentation for ongoing releases.

Local development

This is a Gatsby project that uses the Adobe I/O Theme.

To build the site locally:

1. Clone this repo.

2. Install project dependencies.

   yarn install

3. Launch the project in development mode.

   yarn dev

Components

To achieve specific user experience goals for Commerce documentation, this repo overrides the original Edition component from the upstream aio-theme repo that we use as a dependency.

Edition

The custom Edition component in this repo displays a badge indicating whether a feature or functionality is available in specific Adobe Commerce environments. It has been customized to align with the badges that we use in Experience League docs.

Usage

# Page-level (metadata)
edition: saas # For SaaS-only features
edition: paas # For PaaS-only features

<!-- Section-level (inline) -->
<Edition name="paas" />  <!-- For PaaS-only features -->
<Edition name="saas" />  <!-- For SaaS-only features -->

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 SpectaQL, an open source tool. The data required for the generator is located in the spectaql directory:

• config-admin.yml: configuration file to generate the Channels and Policies API Reference. (Not used in the current implementation, but included for future use.)
• config-merchandising.yml: configuration file to generate the Merchandising Services API Reference.

These configuration files include the endpoint for each API service.

When you build the API reference, the build script uses live introspection to retrieve the GraphQL schemas and generate the API references. The configuration file also provides the introductory text for the Welcome topic, the API reference title, and other settings used when generating the references.

The resulting GraphQL API references are output to the static/graphql-api/ directory.

• static/graphql/admin-api/index.html
• static/graphql/merchandising-api/index.html

The references are embedded in the API Reference page using the frameSrc feature supported by the Adobe I/O theme.

• Channels and Policies API Reference frameSrc: /graphql-api/merchandising-api/index.html

Build commands

To rebuild the GraphQL API references after any updates, use yarn locally to run the following build scripts as needed:

Command	Description
build:merchandising-api	Regenerates the Merchandising API reference
dev:merchandising-api	Regenerates the Merchandising API reference with a live preview of updated output
build:graphql	Regenerates both references

For example, to rebuild the Catalog management and rules API, run the command:

yarn build:admin-api

How to get the schema

The Spectaql configuration files for the Merchandising Services GraphQL API references use the following endpoints to retrieve the schemas and generate the API references:

• Channels and Policies API: https://commerce-admin-router-qa.corp.ethos501-stage-va6.ethos.adobe.net/graphql

• Storefront API: https://catalog-service-qa.adobe.io/graphql

If either of these endpoints change, update the live introspection URL in the corresponding config file in the spectaql directory with the new endpoint.

Update the API References

If a schema changes, rebuild and test the API reference locally. Then, submit a PR with updates against the ccdm-early-access branch. After the PR is merged, someone from the documentation team will publish the changes to the documentation server.

For local builds, ensure that your environment has the following installed:

• Node.js that matches the version set in the .nvmrc (nvm configuration file).
• Yarn

Update schema and regenerate documentation

1. Create a branch from the ccdm-early-access branch.

2. To regenerate an API reference locally and test changes in live preview, use either of the following commands:

   yarn `dev:merchandising-api`

3. Commit changes and push them to your remote branch.

4. Create and submit a PR against the ccdm-early-access branch, and request review from the Commerce Documentation team.

5. After updates are approved, a documentation team member merges the PR and publishes the updates to developer site for Early Access customers.

   View the published API references:

   • Storefront API Reference

Resources

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

REST API Reference Generator

See Generate the Data Ingestion API Reference.