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 and npm -v to determine if node.js is successfully installed.

  NOTE: Restart your IDE after installing node.

• Install a Node Version Manager (nvm)

  • (macOS and Linux) - Node Version Manager
  • (Windows) - nvm-windows

• Install the Adobe aio CLI with the following command:

  Copy
  npm install -g @adobe/aio-cli
  Copied to your clipboard
  npm install -g @adobe/aio-cli

Create a project and workspace

1. In the Adobe Developer Console, select the desired organization from the dropdown in the top-right corner.

2. Then click Create project from template.

3. Select App Builder.

4. Change the Project title to "my_test_workspace".

5. 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:

Copy
npm install -g @adobe/aio-cli-plugin-api-mesh
Copied to your clipboard
npm 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:

Copy
cd my_path/mesh_example
Copied to your clipboard
cd my_path/mesh_example

This directory will contain your mesh.json file, the configuration file for your mesh.

Create a mesh

1. Run the following command to log into Adobe IO:

   Copy
   aio login
   Copied to your clipboard
   aio login

2. Create a file named mesh.json with the following contents:

   Copy
     {
       "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"
               }
             }
           }
         ]
       }
     }
   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 the transforms that manipulate that data. Here we are using venia.magento.com, which is a publicly available Adobe Commerce sample storefront.

3. Run the following command:

   Copy
   aio api-mesh:create mesh.json
   Copied to your clipboard
   aio api-mesh:create mesh.json

4. Use the arrow keys to select the my_test_workspace Project and click Enter. Type y to indicate you want to use this project for future operations. Then press the Enter key.

5. Use the arrow keys to select the stage Workspace and click Enter. Type y and press the Enter key to automatically select this Workspace in the future. You can select another workspace at any time.

6. 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

1. Run the aio api-mesh:describe command and copy the URL for your mesh.

2. Paste the URL into a GraphQL client, such as Altair, GraphiQL, or Insomnia.

3. 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:

Copy
{
  storeConfig {
    store_code
    store_name
    base_currency_code
  }
  GetV1DirectoryCountries {
    ... on directory_data_country_information_interface {
      id
      two_letter_abbreviation
  }
 }
}
Copied to your clipboard
{
  storeConfig {
    store_code
    store_name
    base_currency_code
  }
  GetV1DirectoryCountries {
    ... on directory_data_country_information_interface {
      id
      two_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.

1. Modify your mesh.json file to match the following:

   Copy
   {
     "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_"
               }
             }
           ]
         }
       ]
     }
   }
   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 a prefix to both sources, which will modify field names in the schema to begin with either REST_ or GraphQL_, depending on which source they are from.

2. Update your mesh by using the following command:

   Copy
   aio api-mesh:update mesh.json
   Copied to your clipboard
   aio api-mesh:update mesh.json

3. After 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 the aio api-mesh:status command.

4. Run the following query, which adds both the REST_ and the GraphQL_ prefixes.

   Copy
   {
     storeConfig {
       ... on GraphQL_StoreConfig {
         store_code
         store_name
         base_currency_code
       }
     }
     GetV1DirectoryCountries {
       ... on REST_directory_data_country_information_interface {
         id
         two_letter_abbreviation
       }
     }
   }
   Copied to your clipboard
   {
     storeConfig {
       ... on GraphQL_StoreConfig {
         store_code
         store_name
         base_currency_code
       }
     }
     GetV1DirectoryCountries {
       ... on REST_directory_data_country_information_interface {
         id
         two_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.

1. Run the following source command. The response might ask you to reselect your Workspace and Project.

   Copy
   aio api-mesh:source:install CommerceCatalogServiceGraph
   Copied to your clipboard
   aio api-mesh:source:install CommerceCatalogServiceGraph

2. When you are prompted to enter an API Key, enter a placeholder value like 1234567890 and press the Enter key.

3. After you have successfully added the source, run the following command to view your updated mesh configuration.

Copy
aio api-mesh:get
Copied to your clipboard
aio api-mesh:get

Last updated 7/22/2024

Was this helpful?

Yes

No