bare vs wrap transforms

By default, most transforms work by wrapping the original schema. bare mode replaces the original schema with the transformed one.

Although both bare and wrap modes achieve the same result, their behaviors are very different.

Supported modes

The following table illustrates how bare and wrap modes are supported across different transforms:

bare

Bare mode works by replacing the original schema. The handler generates a GraphQL schema and passes it to the transform. When in bare mode, the transform, receives the schema generated by your handler, applies the defined transform rules, and returns an updated version of the original schema.

The transformed schema replaces the original schema from the handler, so API Mesh deals with the transformed schema only, as opposed to an original schema plus one or more wrapping layers.

bare mode is recommended, however, there are a few restrictions to consider.

Restrictions

bare mode provides performance improvements over wrap mode, however, it needs to access the bare schema. Here are some reasons this might not work:

• Your data source already "speaks" GraphQL bare won't work since it cannot replace a native GraphQL schema. This is not the same as transforming a "translated" GraphQL schema. Instead, we suggest that you apply the wrap transforms to your GraphQL data source and bare transforms to sources "translated" into GraphQL.

• You are applying transforms at the all-sources (root) level This means that bare would receive a composed GraphQL schema, rather than a bare and "translated" schema. If you do want to use bare at the root level, your only choice is to opt into merger-bare, which lets transforms access the bare schemas; because it merges sources without wrapping them. This works when you don't have (or you take care of) conflicts between your sources, and you are not applying root-level transforms to data sources that already "speak" GraphQL.

• You are mixing transforms that support bare with transforms that don't Again, bare mode always needs to access the bare schema. If you define other transforms that don't support bare mode, you will most likely have trouble, because those transforms will apply a wrapping layer that provides the bare transforms, instead of the original bare schema.

To take advantage of bare performance improvements, the suggestion here is to apply wrap transforms at the all-sources (root) level and bare transforms within the data sources level; so you can reduce the number of wrapping layers that would otherwise be created if not using bare at all.

Example:

{
  "sources": [
    {
      "name": "Countries",
      "handler": {
        "graphql": {
          "endpoint": "https://api.../graphql"
        }
      }
    },
    {
      "name": "Users",
      "handler": {
        "openapi": {
          "source": "https://api.../swagger.yaml"
        }
      },
      "transforms": [
        {
          "rename": {
            "mode": "bare",
            "renames": [
              {
                "from": {
                  "type": "User",
                  "field": "lastName"
                },
                "to": {
                  "type": "User",
                  "field": "surname"
                }
              }
            ]
          }
        }
      ]
    }
  ],
  "merger": "bare",
  "transforms": [
    {
      "rename": {
        "mode": "bare",
        "renames": [
          {
            "from": {
              "type": "Country",
              "field": "ISO-3166_Code"
            },
            "to": {
              "type": "Country",
              "field": "code"
            }
          }
        ]
      }
    }
  ]
}

wrap

data-variant=warning

data-slots=text

The wrap mode applies transformations by adding a wrapping layer to the original GraphQL schema. The handler generates a GraphQL schema and passes it to the transform. When in wrap mode, the transform receives this schema. Rather than updating it, it will apply a layer on top of it, with the scope of serving your transformations as an addition to the original schema generated by the handler.

This approach is safe as we have used it extensively in graphql-tools; however, be mindful of the implications below.

Implications

The wrap mode is the default mode for schema manipulation transforms because it is safe and works across all data sources. However, you might want to be aware of the following implications.

• Runtime implications

Schema wrapping is performed during initialization only and so won't affect runtime GraphQL operations. However, transforms that alter the original schema shape using wrap mode, achieve this by intercepting both the incoming request and the original response to do the mapping required to transform the original schema into the desired shape.

Not all transforms require interception of both request and response. Some require straightforward mapping, so the runtime overhead could hopefully be negligible; however, there will always be some.

• Multiple wrapping layers

When using wrap mode, the required transformation can be achieved by adding at least one wrapping layer per each transform rule defined. We cannot have a wrapping layer per transform, but we need one per rule since each rule is unique in the way it transforms different parts of the schema. Some rules might even require multiple wrapping layers, f.i. When transforming a field, the transform needs to be applied to RootFields, ObjectFields, and InputObjectFields.

As explained in the previous point, the wrapping layers are registered during initialization only. However, each wrapping layer will always have some runtime implications, even if hopefully negligible.

• Working with fixed-schema sources

  As mentioned, wrap is the only mode that works for sources that "speak" GraphQL natively. However, when you work with fixed schema sources, such as JSON-schema or OpenApi, schema wrapping might have some undesired effects. For example, you won't have access to the original "fixed-contract" response from your data source.

  This might not be ideal, for example, when implementing custom resolvers, where you might want to access several properties returned by your REST service to compute custom data. Still, you will only be able to access properties requested with the GraphQL query.

  If you don't want/can't opt into bare mode, this can be easily solved by explicitly declaring a SelectionSet, within your custom resolver to list all properties required to compute your custom data.

data-variant=info

data-slots=text

Example:

{
  "sources": [
    {
      "name": "Countries",
      "handler": {
        "graphql": {
          "endpoint": "https://api.../graphql"
        }
      },
      "transforms": [
        {
          "rename": {
            "mode": "wrap",
            "renames": [
              {
                "from": {
                  "type": "Country",
                  "field": "admin1Admins"
                },
                "to": {
                  "type": "Country",
                  "field": "admin1"
                }
              }
            ]
          }
        }
      ]
    },
    {
      "name": "Users",
      "handler": {
        "openapi": {
          "source": "https://api.../swagger.yaml"
        }
      },
      "transforms": [
        {
          "rename": {
            "mode": "wrap",
            "renames": [
              {
                "from": {
                  "type": "User",
                  "field": "lastName"
                },
                "to": {
                  "type": "User",
                  "field": "surname"
                }
              }
            ]
          }
        }
      ]
    }
  ],
  "transforms": [
    {
      "rename": {
        "mode": "wrap",
        "renames": [
          {
            "from": {
              "type": "Country",
              "field": "ISO-3166_Code"
            },
            "to": {
              "type": "Country",
              "field": "code"
            }
          }
        ]
      }
    }
  ]
}

data-variant=info

data-slots=text