id | title | sidebar_label |
---|---|---|
config |
Configuration Guide |
Configuration Guide |
Field | Required | Type | Description |
---|---|---|---|
listen: |
no | string | sets the host and port you want the graphql server to listen on. |
upstreams: |
no | Upstream Map | map of all the upstream severs that you will be accessing with the gateway |
schema: |
no | Schema | |
types: |
no | Types |
Example:
listen: localhost:8080
upstreams:
anilist:
url: https://graphql.anilist.co/
types:
- name: Query
actions:
The upstreams:
section holds a map of all the upstream severs that you will be
accessing with the gateway. The default upstream type is graphql
.
type | Description |
---|---|
graphql |
the upstream server implements graphql |
openapi |
the upstream server implements a REST interface described by an openapi document. |
The graphql
upstream type supports the following configuration options:
Field | Required | Type | Description |
---|---|---|---|
url: |
yes | url | the URL to the graphql endpoint |
prefix: |
no | string | A prefix to add to all upstream graphql Types when they get imported into the gateway graphql schema |
suffix: |
no | string | A suffix to add to all upstream graphql Types when they get imported into the gateway graphql schema |
headers: |
no | Headers | A Headers configuration section |
The openapi
upstream type supports the following configuration options:
Field | Required | Type | Description |
---|---|---|---|
spec: |
yes | Endpoint | Where the openapi specification document can be obtained. |
api: |
no | Endpoint | Sets where endpoint base URL is accessed |
prefix: |
no | string | A prefix to add to all upstream graphql Types when they get imported into the gateway graphql schema |
suffix: |
no | string | A suffix to add to all upstream graphql Types when they get imported into the gateway graphql schema |
headers: |
no | Headers | A Headers configuration section |
A headers section supports the following configuration options:
Field | type | Description |
---|---|---|
disable-forwarding: |
boolean | disables forwarding client set headers to the upstream proxy |
set: |
list of name values | Headers to set on the on the upstream reqeust |
remove: |
list of strings | headers to remove the upstream request |
An Endpoint configuration section supports the following configuration options:
Field | Required | Type | Description |
---|---|---|---|
url: |
yes | url | the URL to the endpoint |
bearer-token: |
yes | string | an Authentication Bearer token that will added to the request headers. |
insecure-client: |
yes | string | allows the client request to connect to TLS servers that do not have a valid certificate. |
api-key: |
yes | string | the API key to use with against the API (as defined in the openapi spec) |
The optional schema section allows you configure the root query type names. The default values of those fields are shown in the folllowing table.
Field | Default |
---|---|
query: |
Query |
mutation: |
Mutation |
schema: |
Subscription |
The example below only the root mutaiton type name is changed from it's default value to GatewayMutation
. Doing something like this can be useful if you do not want to rename type name from an upstream it contains a type name for one of these root query type names.
schema:
mutation: GatewayMutation
Use the types:
section of the configuration to define the fields that can be
accessed by clients of the graphql-link
. You typicaly start by configuring the root query type names
The following example will add a field myfield
to the Query
type where the type is the root query of the anilist
upstream server.
types:
- name: Query
actions:
- type: mount
field: myfield
upstream: anilist
query: query {}
actions:
is a list configuration actions to take against on the named type. The actions are processed in order. You can select from the following actions types:
type | Description |
---|---|
mount |
mounts an upstream field onto a gateway schema type using a graphql query |
rename |
renames either a type or field in the gateway schema. |
remove |
used to remove a field from a type. |
link |
Used to create graph links between types from different servers. |
The mount
action can be used to mount an upstream field onto a gateway schema type using a graphql query
Field | Required | Description |
---|---|---|
upstream: |
yes | a reference to an upstream server defined in the upstreams: section. |
query: |
yes | partial graphql query document to one node in the upstream server graph. |
field: |
no | field name to mount the resulting node on to. not not specified, then all the field of the node are mounted on to the the parent type. |
The link
action is a more advanced version of mount. It is typically used to create new fields that link to data from a different upstream server.
Field | Required | Description |
---|---|---|
upstream: |
yes | a reference to an upstream server defined in the upstreams: section. |
query: |
yes | partial graphql query document to one node in the upstream server graph. |
field: |
yes | field name to mount the resulting node on to. |
vars: |
no | a map of variable names to query selection paths to single leaf node. The selections defined here will be the values passed to the the query: |
The rename
action can be used to rename either a type or field in the gateway schema.
Field | Required | Description |
---|---|---|
field: |
no | if not set, you will be renaming the type, if set, you will be renaming a field of the type. |
to: |
yes | the new name |
The remove
action can be used to remove a field from a type.
Field | Required | Description |
---|---|---|
field: |
yes | The field name to remove from the type |
If you want to import all the fields of an upstream server type, simply don't specify the name for the field to mount the query on to. The following example will import all the query fields onto the Query
type and all the mutation fields on the Mutation
type.
types:
- name: Query
actions:
- type: mount
upstream: anilist
query: query {}
- name: Mutation
actions:
- type: mount
upstream: anilist
query: mutation {}
Use a full graphql query to access nested child graph elements of the upstream graphql server. Feel free to use argument variables or literals in the query. variables used in the query will be translated into arguments for the newly defined field.
types:
- name: Query
actions:
- type: mount
field: pagedCharacterSearch
upstream: anilist
query: |
query ($search:String, $page:Int) {
Page(page:$page, perPage:10) {
characters(search:$search)
}
}
In the example above a pagedCharacterSearch(search:String, page:Int)
field would be defined on the Query type and it would return the type returned by the characters
field of the anilist upstream.