API Mesh tutorial
This tutorial covers the basic actions you can perform in a mesh using API Mesh for Adobe Developer App Builder.
Prerequisites
An Adobe IO account to access the Adobe Developer Console
Install
Node.js
- You can run
node -v
andnpm -v
to determine ifnode.js
is successfully installed.
NOTE: Restart your IDE after installing
node
.- You can run
Install a Node Version Manager (
nvm
)- (macOS and Linux) - Node Version Manager
- (Windows) - nvm-windows
Install the Adobe
aio
CLI with the following command:Copied to your clipboardnpm install -g @adobe/aio-cli
Create a project and workspace
In the Adobe Developer Console, select the desired organization from the dropdown in the top-right corner.
Then click Create project from template.
Select App Builder.
Change the Project title to "my_test_workspace".
Click Save. You now have a project named "my_test_workspace" with workspaces named "Production" and "Stage".
Install the API Mesh plugin
Install the API Mesh plugin with the following command:
Copied to your clipboardnpm install -g @adobe/aio-cli-plugin-api-mesh
Create a local directory
Create a local directory named "mesh_example". Then navigate to that directory in your CLI by using a command similar to:
Copied to your clipboardcd my_path/mesh_example
This directory will contain your mesh.json
file, the configuration file for your mesh.
Create a mesh
Run the following command to log into Adobe IO:
Copied to your clipboardaio loginCreate a file named
mesh.json
with the following contents:Copied to your clipboard{"meshConfig": {"sources": [{"name": "REST","handler": {"openapi": {"source": "https://venia.magento.com/rest/all/schema?services=all"}}},{"name": "GraphQL","handler": {"graphql": {"endpoint": "https://venia.magento.com/graphql"}}}]}}This mesh configuration file specifies the
sources
where you get data from and thetransforms
that manipulate that data. Here we are usingvenia.magento.com
, which is a publicly available Adobe Commerce sample storefront.Run the following command:
Copied to your clipboardaio api-mesh:create mesh.jsonUse the arrow keys to select the
my_test_workspace
Project and click Enter. Typey
to indicate you want to use this project for future operations. Then press the Enter key.Use the arrow keys to select the
stage
Workspace and click Enter. Typey
and press the Enter key to automatically select this Workspace in the future. You can select another workspace at any time.Type
y
and click the Enter key to confirm the creation of the mesh. The mesh configuration and corresponding details will display.It can take a few minutes for new meshes to propagate. If you want to check the build progress, run the
aio api-mesh:status
command. After your mesh is successfully built, proceed to the next section.
Access the Mesh
Run the
aio api-mesh:describe
command and copy the URL for your mesh.Paste the URL into a GraphQL client, such as Altair, GraphiQL, or Insomnia.
Determine if you can view the schema in the Docs section of your GraphQL client. Refer to your GraphQL client's documentation to learn how to access the schema.
If you can view the schema, proceed to the next section. If you cannot view the schema, try the following:
Check your mesh's sources. If you need to modify your mesh, use the
aio api-mesh:update
command to update your mesh with the correct information.Open a web browser and determine if you have access to the Adobe Commerce sample storefront: https://venia.magento.com.
Run a query
In your GraphQL client, run the following GraphQL queries:
Copied to your clipboard{storeConfig {store_codestore_namebase_currency_code}GetV1DirectoryCountries {... on directory_data_country_information_interface {idtwo_letter_abbreviation}}}
These queries demonstrate how you can return data from multiple sources within your mesh with a single request.
The storeConfig
query returns information from the GraphQL
handler, while the GetV1DirectoryCountries query returns information from the REST
handler.
Add a transform
Now we will apply the prefix
transform to prevent conflicting field names between sources. In the following example, we will add REST_
and GraphQL_
prefixes to help us distinguish between our two handlers.
Modify your
mesh.json
file to match the following:Copied to your clipboard{"meshConfig": {"sources": [{"name": "CommerceREST","handler": {"openapi": {"source": "https://venia.magento.com/rest/all/schema?services=all"}},"transforms": [{"prefix": {"value": "REST_"}}]},{"name": "CommerceCoreGraph","handler": {"graphql": {"endpoint": "https://venia.magento.com/graphql"}},"transforms": [{"prefix": {"value": "GraphQL_"}}]}]}}These
transforms
apply aprefix
to both sources, which will modify field names in the schema to begin with eitherREST_
orGraphQL_
, depending on which source they are from.Update your mesh by using the following command:
Copied to your clipboardaio api-mesh:update mesh.jsonAfter you have successfully updated, return to your GraphQL client and open the schema. Search for "GraphQL" or "REST" to see if the
prefix
transform was successful. It can take a few minutes for updated meshes to propagate. You can check the status of your mesh by running theaio api-mesh:status
command.Run the following query, which adds both the
REST_
and theGraphQL_
prefixes.Copied to your clipboard{storeConfig {... on GraphQL_StoreConfig {store_codestore_namebase_currency_code}}GetV1DirectoryCountries {... on REST_directory_data_country_information_interface {idtwo_letter_abbreviation}}}
Add a source
You can use the source commands to install preconfigured first and third-party sources. You can find available sources by running the aio api-mesh:source:discover
command or visiting the Adobe api-mesh-sources repository.
Run the following source command. The response might ask you to reselect your Workspace and Project.
Copied to your clipboardaio api-mesh:source:install CommerceCatalogServiceGraphWhen you are prompted to enter an API Key, enter a placeholder value like
1234567890
and press the Enter key.After you have successfully added the source, run the following command to view your updated mesh configuration.
Copied to your clipboardaio api-mesh:get