Skip to main content
Version: v2.x

Metadata API Reference: Remote Schemas

Introduction

Add/Remove a remote GraphQL server as Remote Schema in Hasura GraphQL engine.

Supported from

The Metadata API is supported for versions v2.0.0 and above and replaces the older schema/Metadata API.

add_remote_schema

add_remote_schema is used to add a remote GraphQL server as remote schema. GraphQL Engine stitches it's schema with existing.

An example request as follows:

POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
"type": "add_remote_schema",
"args": {
"name": "my remote schema",
"definition": {
"url": "https://remote-server.com/graphql",
"headers": [{"name": "X-Server-Request-From", "value": "Hasura"}],
"forward_client_headers": false,
"timeout_seconds": 60,
"customization": {
"root_fields_namespace": "some_field_name",
"type_names": {
"prefix": "some_type_name_prefix",
"suffix": "some_type_name_suffix",
"mapping": {
"some_type_name": "some_new_type_name"
}
},
"field_names": [ {
"parent_type": "some_type_name",
"prefix": "some_field_name_prefix",
"suffix": "some_field_name_suffix",
"mapping": {
"some_field_name": "some_new_field_name"
}
} ]
}
},
"comment": "some optional comment"
}
}

Args syntax

KeyRequiredSchemaDescription
nametrueRemoteSchemaNameName of the Remote Schema
definitiontrueRemoteSchemaDefDefinition for the Remote Schema
commentfalseTextcomment

update_remote_schema

update_remote_schema is used to update the configuration of a remote schema. If the Remote Schema URL has changed then it will perform a introspection as well. After introspection, if there are any inconsistencies detected with other Metadata objects (like remote relationships or Remote Schema permissions) they will be reported as

inconsistent_metadata.

An example request as follows:

POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
"type": "update_remote_schema",
"args": {
"name": "my remote schema",
"definition": {
"url": "https://remote-server.com/graphql",
"headers": [{"name": "X-Server-Request-From", "value": "Hasura"}],
"forward_client_headers": false,
"timeout_seconds": 60,
"customization": {
"root_fields_namespace": "some_field_name",
"type_names": {
"prefix": "some_type_name_prefix",
"suffix": "some_type_name_suffix",
"mapping": {
"some_type_name": "some_new_type_name"
}
},
"field_names": [ {
"parent_type": "some_type_name",
"prefix": "some_field_name_prefix",
"suffix": "some_field_name_suffix",
"mapping": {
"some_field_name": "some_new_field_name"
}
} ]
}
},
"comment": "some optional comment"
}
}

Args syntax

KeyRequiredSchemaDescription
nametrueRemoteSchemaNameName of the Remote Schema
definitiontrueRemoteSchemaDefDefinition for the Remote Schema
commentfalseTextcomment

remove_remote_schema

remove_remote_schema is used to delete a Remote Schema. GraphQL Engine de-stitches it's schema.

An example request as follows:

POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
"type": "remove_remote_schema",
"args": {
"name": "my remote schema"
}
}

Args syntax

KeyRequiredSchemaDescription
nametrueRemoteSchemaNameName of the Remote Schema

reload_remote_schema

reload_remote_schema is used to refresh schema of the remote server. GraphQL Engine refetches schema from server and stitches.

An example request as follows:

POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
"type": "reload_remote_schema",
"args": {
"name": "my remote schema"
}
}

Args syntax

KeyRequiredSchemaDescription
nametrueRemoteSchemaNameName of the Remote Schema