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

Key	Required	Schema	Description
name	true	RemoteSchemaName	Name of the remote schema
definition	true	RemoteSchemaDef	Definition for the remote schema
comment	false	Text	comment

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

Key	Required	Schema	Description
name	true	RemoteSchemaName	Name of the remote schema
definition	true	RemoteSchemaDef	Definition for the remote schema
comment	false	Text	comment

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

Key	Required	Schema	Description
name	true	RemoteSchemaName	Name 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

Key	Required	Schema	Description
name	true	RemoteSchemaName	Name of the remote schema