mirror of
https://github.com/hasura/graphql-engine.git
synced 2024-12-17 04:24:35 +03:00
866476ab36
GITHUB_PR_NUMBER: 8011 GITHUB_PR_URL: https://github.com/hasura/graphql-engine/pull/8011 PR-URL: https://github.com/hasura/graphql-engine-mono/pull/3317 Co-authored-by: Rikin Kachhia <54616969+rikinsk@users.noreply.github.com> GitOrigin-RevId: 90c8f75003a07c5153c9e478efa599ab0bfb85d9
186 lines
6.6 KiB
ReStructuredText
186 lines
6.6 KiB
ReStructuredText
.. meta::
|
|
:description: Add a remote schema with Hasura
|
|
:keywords: hasura, docs, remote schema, add
|
|
|
|
.. _adding_schema:
|
|
|
|
Adding a remote schema
|
|
======================
|
|
|
|
.. contents:: Table of contents
|
|
:backlinks: none
|
|
:depth: 2
|
|
:local:
|
|
|
|
Introduction
|
|
------------
|
|
|
|
Follow the steps below to merge your remote schema with the GraphQL engine's auto-generated schema.
|
|
|
|
Step 0: Write a custom GraphQL server
|
|
-------------------------------------
|
|
|
|
*If you already have a functional GraphQL server that meets your requirements, you can skip this step.*
|
|
|
|
You need to create a custom GraphQL server with a schema and corresponding resolvers that solve your use case
|
|
|
|
You can use any language/framework of your choice to author this server and deploy it anywhere. A great way to get
|
|
started is to use one of our `boilerplates <https://github.com/hasura/graphql-engine/tree/master/community/boilerplates/remote-schemas>`__
|
|
|
|
.. _merge_remote_schema:
|
|
|
|
Step 1: Merge remote schema
|
|
---------------------------
|
|
|
|
The following details need to be specified for merging a remote schema:
|
|
|
|
- **Remote Schema name**: an alias for the remote schema that must be unique on an instance of the GraphQL engine.
|
|
|
|
- **GraphQL server URL**: the endpoint at which your remote GraphQL server is available. This value can be entered
|
|
manually or by specifying an environment variable that contains this information.
|
|
|
|
- **Headers**: configure the headers to be sent to your custom GraphQL server:
|
|
|
|
- Toggle forwarding all headers sent by the client (when making a GraphQL query) to your remote GraphQL server.
|
|
|
|
- Send additional headers to your remote server - these can be static header name-value pairs; and/or pairs of
|
|
"header name-environment variable name". You can specify the value of the header to be picked up from the environment
|
|
variable.
|
|
|
|
**Example**: Let's say your remote GraphQL server needs a ``X-Api-Key`` as a header. As this value contains
|
|
sensitive data (like API key in this example), you can configure the name of an environment variable which will hold
|
|
the value. This environment variable needs to be present when you start the GraphQL engine. When Hasura sends
|
|
requests to your remote server, it will pick up the value from this environment variable.
|
|
|
|
|
|
.. rst-class:: api_tabs
|
|
.. tabs::
|
|
|
|
.. tab:: Console
|
|
|
|
Head to the ``Remote Schemas`` tab of the console and click on the ``Add`` button on the left sidebar.
|
|
|
|
Add the required details and click on the ``Add Remote Schema`` button to merge the remote schema.
|
|
|
|
.. thumbnail:: /img/graphql/core/remote-schemas/add-remote-schemas-interface.png
|
|
:alt: Merge remote schema
|
|
:width: 1100px
|
|
|
|
.. tab:: CLI
|
|
|
|
To add a remote schema, edit the ``remote_schemas.yaml`` file in the ``metadata`` directory as in this example:
|
|
|
|
.. code-block:: yaml
|
|
:emphasize-lines: 1-5
|
|
|
|
- name: my-remote-schema
|
|
definition:
|
|
url: https://graphql-pokemon.now.sh/
|
|
timeout_seconds: 60
|
|
forward_client_headers: true
|
|
|
|
Apply the metadata by running:
|
|
|
|
.. code-block:: bash
|
|
|
|
hasura metadata apply
|
|
|
|
.. tab:: API
|
|
|
|
You can add a remote schema by using the :ref:`metadata_add_remote_schema` metadata API:
|
|
|
|
.. code-block:: http
|
|
|
|
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://graphql-pokemon.now.sh/",
|
|
"forward_client_headers": true,
|
|
"timeout_seconds": 60
|
|
}
|
|
}
|
|
}
|
|
|
|
|
|
.. note::
|
|
|
|
If you are running Hasura using Docker, ensure that the Hasura Docker container can reach the server endpoint.
|
|
See :ref:`this page <docker_networking>` for Docker networking.
|
|
|
|
If you are adding the URL using env variable, then run the Hasura docker container with the env variable added
|
|
during `docker run`. Example ``-e REMOTE_SCHEMA_ENDPOINT=http://host.docker.internal:4000/mycustomgraphql``.
|
|
|
|
.. admonition:: Using environment variables
|
|
|
|
If you are using environment variables in the remote schema configuration - either
|
|
for URL or headers - **the environment variables need to be present** with valid values
|
|
when adding the remote schema i.e. the GraphQL engine should be started with these environment variables.
|
|
|
|
Step 2: Make queries to the remote server from Hasura
|
|
-----------------------------------------------------
|
|
|
|
.. rst-class:: api_tabs
|
|
.. tabs::
|
|
|
|
.. tab:: Via console
|
|
|
|
Now you can head to the ``GraphiQL`` tab and make queries to your remote server from Hasura.
|
|
|
|
.. tab:: Via API
|
|
|
|
You can query your remote server by making requests to the Hasura GraphQL endpoint (``/v1/graphql``).
|
|
|
|
Points to remember
|
|
------------------
|
|
|
|
Remote schema fields nomenclature
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
- Top-level field names need to be unique across all merged schemas (*case-sensitive match*).
|
|
- Types with the *exact same name and structure* will be merged. But types with the *same name but different
|
|
structure* will result in type conflicts.
|
|
|
|
|
|
Schema refreshing
|
|
^^^^^^^^^^^^^^^^^
|
|
|
|
A remote server's GraphQL schema is cached and refreshed only when user explicitly reloads the remote schema.
|
|
|
|
.. rst-class:: api_tabs
|
|
.. tabs::
|
|
|
|
.. tab:: Console
|
|
|
|
Head to ``Remote Schemas -> [remote_schema_name] -> Details`` and click the ``Reload`` button.
|
|
|
|
.. tab:: API
|
|
|
|
Make a request to the :ref:`metadata_reload_remote_schema` metadata API.
|
|
|
|
Current limitations
|
|
^^^^^^^^^^^^^^^^^^^
|
|
|
|
- Subscriptions on remote GraphQL servers are not supported.
|
|
|
|
Extending the auto-generated GraphQL schema fields
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
For some use cases, you may need to extend the GraphQL schema fields exposed by the Hasura GraphQL engine and not merely add new fields as we have done here.
|
|
|
|
To achieve this you can use community tooling to write your own client-facing GraphQL gateway which wraps around and interacts with the GraphQL engine API underneath.
|
|
|
|
.. note::
|
|
|
|
**Adding an additional layer on top of the Hasura GraphQL engine significantly impacts the performance provided by
|
|
it out of the box** (*by as much as 4x*). If you need any help with remodelling these kinds of use cases to use the
|
|
built-in remote schemas feature, please get in touch with us on `GitHub <https://github.com/hasura/graphql-engine/discussions>`__.
|
|
|
|
.. admonition:: Additional Resources
|
|
|
|
Data Federation with Hasura - `Watch Webinar <https://hasura.io/events/webinar/data-federation-hasura-graphql/?pg=docs&plcmt=body&cta=watch-webinar&tech=>`__. |