degraphql

Maps REST endpoints onto a GraphQL upstream.

Category TransformationAdd it to Route, Service, Consumer, Consumer group, Global rule, Plugin configEngine plugin degraphqlPriority 509

What it does

degraphql turns a plain REST call on a route into a GraphQL query for the backend. The backend receives the Query written here instead of the client's request, with the names listed under Variables read from the request and passed as variables.

The route's upstream is the GraphQL server itself. A GET sends the query to it as query arguments, and a POST as a JSON body.

When to use it

• An orders API whose backend speaks only GraphQL, offered to partners as plain paths they can call without writing a query.
• A mobile app that fetches one order by its ID with a GET, while the GraphQL server keeps one schema for every client.
• A route that should run one fixed query and nothing else, whatever the client sends.

Not for caching the answers to GraphQL queries — see graphql-proxy-cache (Caches GraphQL responses), rewriting a request body by a template of your own — see body-transformer (Rewrites request and response bodies with templates) or changing the path or headers of a request on its way — see proxy-rewrite (Rewrites the request URI, method, host and headers before proxying).

Set it up

Serve a GraphQL query as a plain REST endpoint

The route's upstream is the GraphQL server; a GET reads id from the query string, a POST from its JSON body.

Set Query to query Order($id: ID!) { order(id: $id) { id status total } }, set Operation name to Order and fill Variables as in the JSON below.

degraphql · as the console saves it

{
  "query": "query Order($id: ID!) { order(id: $id) { id status total } }",
  "operation_name": "Order",
  "variables": [
    "id"
  ]
}

Things to know

• Variables — In the example a GET with ?id=42 reaches the GraphQL server with the operation Order and id among its variables. The value travels as the text 42, not as a number.
• Query — Parsed while the write is checked, and a text holding more than one operation is refused unless an operation name is set.
• Query — A request with a method other than GET or POST is answered 405.
• Variables — With names listed, a POST without a JSON body is refused with 400. A GET reads the names from the query string.
• Request body limit — Over this a request is answered 503 while variables are listed above, and 500 where none are.
• AdviceGive each variable in the query a type that accepts text, ID for an identifier for example.

Settings

The fields as the console shows them, section by section.

QueryquerystringRequired

The GraphQL query sent upstream instead of the client's, such as query { me { id } }. POST sends it as a JSON body, GET as query arguments. Other methods are refused with 405.

1 to 1024 characters · example query Hero($id: ID) { hero(id: $id) { name } }

Operation nameoperation_namestring

The operation to run when the query holds several. A name the query does not contain is still saved and sent.

1 to 1024 characters

Variablesvariablesarray of strings

Names read from the request, such as id, and passed to the query as variables. A POST reads them from its JSON body, a GET from its query string.

at least 1 item

Request body limitmax_req_body_sizeintegerdefault 67108864

Bytes of the request body read before it is replaced by the GraphQL body.

at least 1

Every plugin also has Enabled, Priority, Filter, Error response and Pre-function: see Plugin execution settings.