OpenAPI

The OpenAPI connector allows you to load remote OpenAPI (2/3.0/3.1) and Swagger schemas that are added to the Edge Gateway inside of the provided namespace.

The OpenAPI connector accepts the following config:

• name (required) — The unique name for the API
• url (optional) — The URL used to execute requests*
• schema — The OpenAPI (2/3) and Swagger schema
• headers (optional) — The static or forwarded headers sent with requests
• transforms — Any schema transformations to be applied

import { config, connector, graph } from '@grafbase/sdk'

const g = graph.Standalone()

const stripe = connector.OpenAPI('Stripe', {
  schema:
    'https://raw.githubusercontent.com/stripe/openapi/master/openapi/spec3.json',
  headers: headers => {
    headers.set('Authorization', `Bearer ${g.env('STRIPE_API_KEY')}`)
  },
})

g.datasource(stripe)

export default config({ graph: g })

Query Naming

The OpenAPI connector names the generated query fields after their underlying resources. But some OpenAPI schemas are structured around requests & responses rather than resources.

In these cases the generated query field names can be improved using the optional operationId value which is a unique value used to identify an operation.

To enable this you must pass OPERATION_ID.

import { config, connector, graph } from '@grafbase/sdk'

const g = graph.Standalone()

const mux = connector.OpenAPI('Mux', {
  schema: 'https://docs.mux.com/api-spec.json',
  headers: headers => {
    headers.set('Authorization', `Basic ${g.env('MUX_BASE64')}`)
  },
  transforms: schema => {
    schema.queryNaming('OPERATION_ID')
  },
})

g.datasource(mux)

export default config({ graph: g })

The OpenAPI connector provides transforms that allow you to modify the shape of the API exposed from Grafbase.

If you want to remove one or more fields from the API, you can use the exclude transform. This accepts one or more dot separated paths specifying the fields you'd like to exclude. You can also use wildcards to select all the fields of a given type.

import { config, connector, graph } from '@grafbase/sdk'

const g = graph.Standalone()

const identity = connector.OpenAPI('IdentityApi', {
  schema: g.env('IDENTITY_API_SCHEMA'),
  transforms: schema => {
    // Hide some sensitive fields of the User type
    schema.exclude('User.password', 'User.secret_key')

    // Hide all mutations
    schema.exclude('Mutations.*')
  },
})

g.datasource(identity)

export default config({ graph: g })

When using Grafbase to connect many different data sources together, there's a chance you'll end up with two different types with the same name. Grafbase uses type prefixes by default to avoid these: we take the name of the type and put a prefix on that name before we pull it into our API.

By default we use the name of the data source for this. But it can be controlled using the prefixTypes transform:

import { config, connector, graph } from '@grafbase/sdk'

const g = graph.Standalone()

const cms = connector.OpenAPI('FancyCms', {
  schema: g.env('FANCY_CMS_SCHEMA'),
  transforms: schema => {
    // Change the typePrefix to Cms
    schema.prefixTypes('Cms')
  },
})

g.datasource(cms)

export default config({ graph: g })

This can also be used to remove the prefix:

import { config, connector, graph } from '@grafbase/sdk'

const g = graph.Standalone()

const cms = connector.OpenAPI('FancyCms', {
  schema: g.env('FANCY_CMS_SCHEMA'),
  transforms: schema => {
    // Remove the prefix
    schema.prefixTypes('')
  },
})

g.datasource(cms)

export default config({ graph: g })