Connectors

The Grafbase Edge Gateway allows you to unify data at the edge by glueing GraphQL and non-GraphQL services together.

Connectors work by extending the root schema inside grafbase/schema.graphql.

The @openapi directive allows you to load remote OpenAPI (2/3) and Swagger schemas that are added to the Edge Gateway inside of the provided namespace value.

• name — The namespace for the OpenAPI
• url (optional) — The URL used to execute requests*
• schema — The OpenAPI (2/3) and Swagger schema
• headers (optional) — The headers forwarded with each request
• introspectionHeaders (optional) — The headers forwarded with requests to fetch the schema

extend schema
  @openapi(
    name: "Stripe"
    schema: "https://raw.githubusercontent.com/stripe/openapi/master/openapi/spec3.json"
    headers: [
      { name: "Authorization", value: "Bearer {{ env.STRIPE_API_KEY }}" }
    ]
  ) {
  query: Query
}

The @graphql directive allows you to merge remote GraphQL APIs with your existing project API using the Edge Gateway.

• name — The namespace for the GraphQL API
• url — The URL used to execute requests and introspection
• headers (optional) — The headers forwarded with each request
• introspectionHeaders (optional) — The headers forwarded with requests to fetch the schema

extend schema
  @graphql(
    name: "Contentful"
    url: "https://graphql.contentful.com/content/v1/spaces/{{ env.CONTENTFUL_SPACE_ID }}/environments/{{ env.CONTENTFUL_ENVIRONMENT }}"
    headers: [
      { name: "Authorization", value: "Bearer {{ env.CONTENTFUL_API_KEY }}" }
    ]
  ) {
  query: Query
}

Combine multiple data sources by adding additional connector directives.

extend schema
  @openapi(
    name: "Stripe"
    schema: "https://raw.githubusercontent.com/stripe/openapi/master/openapi/spec3.json"
  )
  @openapi(
    name: "OpenAI"
    schema: "https://raw.githubusercontent.com/openai/openai-openapi/master/openapi.yaml"
  ) {
  query: Query
}

You can extend connected API types and access root fields with resolvers:

extend type StripeCustomer {
  myField(myArg: String): String @resolver(name: "file")
}

Connectors can also use environment variables locally with the CLI, and in production.

extend schema
  @openapi(
    name: "Stripe"
    schema: "{{ env.STRIPE_SCHEMA_URL }}"
    headers: [
      { name: "Authorization", value: "Bearer {{ env.STRIPE_API_KEY }}" }
    ]
  ) {
  query: Query
}

Connectors create a namespace inside the schema for type Query and type Mutation by using the name provided the connector directive.

type Query {
  stripe: StripeQuery!
  github: GithubQuery!
}

type Mutation {
  stripe: StripeMutation!
  github: GithubMutation!
}

You can enable caching to connected APIs using the @cache directive:

extend schema
  @graphql(
    name: "Contentful"
    url: "https://graphql.contentful.com/content/v1/spaces/{{ env.CONTENTFUL_SPACE_ID }}/environments/{{ env.CONTENTFUL_ENVIRONMENT }}"
    headers: [
      { name: "Authorization", value: "Bearer {{ env.CONTENTFUL_API_KEY }}" }
    ]
  )
  @cache(
    rules: [
      { types: ["ContentfulQuery"], maxAge: 60, staleWhileRevalidate: 60 }
    ]
  ) {
  query: Query
}