API Namespacing

Problem

When working with multiple APIs, developers often face the challenge of naming collisions when merging two different schemas. This occurs when two schemas have identical type names, leading to confusion and errors during the resolution process. As a result, it becomes difficult to determine which schema should be used for a specific operation.

Solution

To tackle this issue, WunderGraph (opens in a new tab) introduces the concept of API namespacing (opens in a new tab). This approach ensures that all type names are isolated within their relevant API namespaces, allowing the GraphQL Engine to understand which schema to resolve without any ambiguity.

How Namespacing Works

Namespacing isolates type names by prefixing them with a unique identifier associated with the API. This ensures that each type name remains distinct and avoids naming collisions when merging schemas. By incorporating namespacing, developers can effectively combine multiple APIs without worrying about potential conflicts or errors.

Prefixed Directives for Error Prevention

WunderGraph also utilizes prefixed directives to help prevent errors during the merging process. These directives act as markers, indicating to the GraphQL Engine which namespace a specific type or field belongs to. By using prefixed directives, developers can ensure that the engine accurately resolves the appropriate schema, reducing the risk of errors.

Example of Prefixed Directive in Use

Consider two APIs, API_A and API_B, both containing a type named User. To avoid naming collisions, WunderGraph namespaces these types as API_A_User and API_B_User. When querying the merged schema, developers can use the prefixed directive @API_A or @API_B to specify the desired API:

query {
  API_A_User: api_a {
    id
    name
  }
  API_B_User: api_b {
    id
    email
  }
}

In this example, the prefixed directives api_a and api_b ensure that the GraphQL Engine resolves the correct schema for each User type.

Simplifying the Process for Developers

By implementing namespacing and prefixed directives, WunderGraph makes it easier for developers to combine multiple APIs within a single project. This approach streamlines the development process, reduces the risk of errors, and allows developers to focus on building robust applications without worrying about naming collision challenges.

In conclusion, WunderGraph's API namespacing (opens in a new tab) solution addresses the common issue of naming collisions when merging schemas, simplifying the process for developers and ensuring a more efficient and error-free development experience.