Work with your mesh

This page describes ways you can work with meshes that contain optional processes that are not required for mesh creation.

Retrieve a previously created `meshId` or mesh endpoint URL

If you need to retrieve a meshId or mesh endpoint URL from a previously created mesh, use the following command to display your mesh details in the console.

aio api-mesh:describe
Copied to your clipboard
aio api-mesh:describe

By default, the command describes the mesh in the selected project and workspace.

If no project or workspace is selected, the command returns a list of projects. Use the arrow and enter keys to select your project and organization. Alternatively, you can type to search for your project and workspace.

Move a mesh to another workspace

You may need to move a mesh from one workspace to another, for example from stage to production. The following process describes how to copy a mesh from one workspace and duplicate it in another workspace.

Select the workspace that contains the mesh you want to copy.
Retrieve your previously created mesh by running the following get command.
```
aio api-mesh:get download.json
Copied to your clipboard
aio api-mesh:get download.json
```
This command creates a file named download.json that contains a copy of the mesh from the selected workspace.

Run the following command and select the production or target workspace, see select a project or workspace for more information.

aio console:workspace:select
Copied to your clipboard
aio console:workspace:select

Run the create command and reference the previously created file.

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

Include `httpDetails` in query responses

Adding the includeHTTPDetails flag to your JSON mesh configuration file determines if httpDetails information is included in query responses.

Setting includeHTTPDetails to true adds information like responseTime and response headers to every query response. Setting includeHTTPDetails to false prevents users who query your mesh from accessing this information. If you do not include the includeHTTPDetails property in your mesh, the setting defaults to false.

The following example mesh indicates the location of the includeHTTPDetails flag.

{
    "meshConfig": {
        "responseConfig":{
            "includeHTTPDetails":true

        },
        "sources":[
            {
                "name":"Venia",
                "handler": {
                    "graphql": 
                    {
                        "endpoint":"https://venia.magento.com/graphql"
                    }
                }
            }
        ]
    }
}
Copied to your clipboard
{
    "meshConfig": {
        "responseConfig":{
            "includeHTTPDetails":true

        },
        "sources":[
            {
                "name":"Venia",
                "handler": {
                    "graphql": 
                    {
                        "endpoint":"https://venia.magento.com/graphql"
                    }
                }
            }
        ]
    }
}

When you query a mesh with includeHTTPDetails set to true, the response will include an httpDetails section with the following information:

sourceName
request
response
responseTime

The following example includes some additional information a user can receive as part of the response. The exact response varies, depending on your source handlers, headers, and other customizations.

{   
 "data": {
        "storeConfig": {
            "timezone": "America/Los_Angeles"
        }
    },
    "extensions": {
        "httpDetails": [
            {
                "sourceName": "Venia",
                "request": {
                    "timestamp": 1676489418840,
                    "url": "https://venia.magento.com/graphql",
                    "method": "POST",
                    "headers": {
                        "accept": "application/graphql-response+json, application/json, multipart/mixed",
                        "content-type": "application/json"
                    }
                },
                "response": {
                    "timestamp": 1676489419070,
                    "status": 200,
                    "statusText": "OK",
                    "headers": {
                        "accept-ranges": "bytes",
                        "cache-control": "max-age=0, must-revalidate, no-cache, no-store",
                        "connection": "keep-alive",
                        "content-length": "63",
                        "content-type": "application/json",
                        "date": "Wed, 15 Feb 2023 19:30:19 GMT",
                        "expires": "Tue, 15 Feb 2022 19:30:19 GMT",
                    }
                },
                "responseTime": 230
            }
        ]
    }
}
Copied to your clipboard
{   
 "data": {
        "storeConfig": {
            "timezone": "America/Los_Angeles"
        }
    },
    "extensions": {
        "httpDetails": [
            {
                "sourceName": "Venia",
                "request": {
                    "timestamp": 1676489418840,
                    "url": "https://venia.magento.com/graphql",
                    "method": "POST",
                    "headers": {
                        "accept": "application/graphql-response+json, application/json, multipart/mixed",
                        "content-type": "application/json"
                    }
                },
                "response": {
                    "timestamp": 1676489419070,
                    "status": 200,
                    "statusText": "OK",
                    "headers": {
                        "accept-ranges": "bytes",
                        "cache-control": "max-age=0, must-revalidate, no-cache, no-store",
                        "connection": "keep-alive",
                        "content-length": "63",
                        "content-type": "application/json",
                        "date": "Wed, 15 Feb 2023 19:30:19 GMT",
                        "expires": "Tue, 15 Feb 2022 19:30:19 GMT",
                    }
                },
                "responseTime": 230
            }
        ]
    }
}

Projects and workspaces

When creating a mesh for the first time, you must select the project and workspace that you want to create the mesh in. Alternatively, you can use aio commands to manually select a project or workspace, list the current selections, or remove the currently selected project or workspace from the cache.

View the cached project and workspace

To see your current cache configuration, use the aio config:get console command, which includes the currently selected organization, project, and workspace.

You can view a list of available projects in your current organization by running the aio console:project:list command.

To view a list of available workspaces in the current project, run the aio console:workspace:list command.

Select a project or workspace

By default, projects have a production and a stage workspace. You can also create your own workspaces. If you do not know which workspace to use, use the stage workspace.

To change the selected project, use the aio console:project:select command, which prompts you to select your project from a list.

To change the selected workspace, use the aio console:workspace:select command, which prompts you to select your workspace from a list.

You must select a project before you select a workspace.

Delete a cached project or workspace

If you want to clear a previously selected project or workspace from your cache, use the aio config:delete followed by the object you want to remove from your cached config.

For example:

aio config:delete console.project Removes the current project from the cache.
aio config:delete console.workspace Removes the current workspace from the cache.

Aliasing

In GraphQL you can use aliasing in your query to rename fields and avoid fields with conflicting names. This is particularly useful for API Mesh because aliasing allows you to rename fields when querying.

You can also rename field names within your mesh by using the rename and prefix transforms.

The following example renames the name field to productName.

{
 products(search:"tops"){
   items {
       productName:name
       sku
     }
   } 
 } 
Copied to your clipboard
{
 products(search:"tops"){
   items {
       productName:name
       sku
     }
   } 
 }

Due to the limitations of API Mesh, responses contain both the newly created alias field and the original field. For example, the previous query produces the following response that contains both the aliased field, productName, and the original field, name.

{
  "data": {
    "products": {
      "CommerceItems": [
        {
          "productName": "Vitalia Top",
          "sku": "VT10",
          "name": "Vitalia Top"
        },
        {
          "productName": "Jillian Top",
          "sku": "VT12",
          "name": "Jillian Top"
        }
      ]
    }
  }
}
Copied to your clipboard
{
  "data": {
    "products": {
      "CommerceItems": [
        {
          "productName": "Vitalia Top",
          "sku": "VT10",
          "name": "Vitalia Top"
        },
        {
          "productName": "Jillian Top",
          "sku": "VT12",
          "name": "Jillian Top"
        }
      ]
    }
  }
}

Chained mutations

When you query a mesh using chained mutations, the mesh makes a separate call to the source for each mutation. This happens because GraphQL requests execute when the GraphQL server receives them, instead of proxying the calls. Because API Mesh supports multiple sources, it evaluates batched mutations and separates the information based on the source it is associated with.

These mutations are executed sequentially, calling one source after the other. When you call a source directly, it will only need one API call, but it will execute the batch mutations sequentially by calling their respective resolvers. These calls are more overt in API Mesh, because they are made by a network call, instead of an internal call. This means you will see multiple calls for chained mutations.

Create a mesh

Local development