degraphql

    We use docker to deploy a GraphQL server demo as the backend.

    After starting the server, the following endpoints are now available:

    Enabling the Plugin

    Query list

    If we have a GraphQL query like this:

    1. query {
    2.   persons {
    3.     id
    4.     name
    5.   }
    6. }

    We can execute it on http://localhost:8080/playground, and get the data as below:

    1. {
    2.   "data": {
    3.     "persons": [
    4.       {
    5.         "id": "7",
    6.         "name": "Niek"
    7.       },
    8.       {
    9.         "id": "8",
    10.         "name": "Josh"
    11.       },
    12.       ......
    13.     ]
    14.   }
    15. }

    Now we can use RESTful API to query the same data that is proxy by APISIX.

    First, we need to create a route in APISIX, and enable the degreaph plugin on the route, we need to define the GraphQL query in the plugin’s config.

    1. curl --location --request PUT 'http://localhost:9080/apisix/admin/routes/1' \
    2. --header 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' \
    3. --header 'Content-Type: application/json' \
    4. --data-raw '{
    5.     "uri": "/graphql",
    6.     "upstream": {
    7.         "type": "roundrobin",
    8.         "nodes": {
    9.             "127.0.0.1:8080": 1
    10.         }
    11.     },
    12.     "plugins": {
    13.         "degraphql": {
    14.             "query": "{\n  persons {\n    id\n    name\n  }\n}\n"
    15.         }
    16.     }
    17. }'
    1. {
    2.   persons {
    3.     id
    4.     name
    5.   }
    6. }

    to JSON string "{\n persons {\n id\n name\n }\n}\n", and put it in the plugin’s configuration.

    Then we can query the data by RESTful API:

    and get the result:

    1. {
    2.   "data": {
    3.     "persons": [
    4.       {
    5.         "id": "7",
    6.       },
    7.       {
    8.         "id": "8",
    9.         "name": "Josh"
    10.       },
    11.       ......
    12.     ]
    13.   }

    Query with variables

    If we have a GraphQL query like this:

    1. query($name: String!, $githubAccount: String!) {
    2.   persons(filter: { name: $name, githubAccount: $githubAccount }) {
    3.     id
    4.     name
    5.     blog
    6.     githubAccount
    7.     talks {
    8.       id
    9.       title
    10.     }
    11.   }
    12. }
    14. variables:
    15. {
    16.   "name": "Niek",
    17.   "githubAccount": "npalm"
    18. }

    we can execute it on http://localhost:8080/playground, and get the data as below:

    1. {
    2.   "data": {
    3.     "persons": [
    4.       {
    5.         "id": "7",
    6.         "name": "Niek",
    7.         "blog": "https://040code.github.io",
    8.         "githubAccount": "npalm",
    9.         "talks": [
    10.           {
    11.             "id": "19",
    12.             "title": "GraphQL - The Next API Language"
    13.           },
    14.           {
    15.             "id": "20",
    16.             "title": "Immutable Infrastructure"
    17.           }
    18.         ]
    19.       }
    20.     ]
    21.   }
    22. }

    We convert the GraphQL query to JSON string like "query($name: String!, $githubAccount: String!) {\n persons(filter: { name: $name, githubAccount: $githubAccount }) {\n id\n name\n blog\n githubAccount\n talks {\n id\n title\n }\n }\n}", so we create a route like this:

    1. curl --location --request PUT 'http://localhost:9080/apisix/admin/routes/1' \
    2. --header 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' \
    3. --header 'Content-Type: application/json' \
    4. --data-raw '{
    5.     "uri": "/graphql",
    6.     "upstream": {
    7.         "type": "roundrobin",
    8.         "nodes": {
    9.             "127.0.0.1:8080": 1
    10.         }
    11.     },
    12.     "plugins": {
    13.         "degraphql": {
    14.             "variables": [
    15.                 "name",
    16.                 "githubAccount"
    17.             ]
    19.     }
    20. }'

    Query the data by RESTful API that proxy by APISIX:

    and get the result:

    1. {
    2.   "data": {
    3.     "persons": [
    4.       {
    5.         "id": "7",
    6.         "name": "Niek",
    7.         "blog": "https://040code.github.io",
    8.         "githubAccount": "npalm",
    9.         "talks": [
    10.           {
    11.             "id": "19",
    12.             "title": "GraphQL - The Next API Language"
    13.           },
    14.           {
    15.             "id": "20",
    16.             "title": "Immutable Infrastructure"
    17.           }
    18.         ]
    19.       }
    20.     ]
    21.   }
    22. }

    which is the same as the result of the GraphQL query.

    It’s also possible to get the same result via GET request:

    1. curl 'http://localhost:9080/graphql?name=Niek&githubAccount=npalm'
    1. {
    2.   "data": {
    3.     "persons": [
    4.       {
    5.         "id": "7",
    6.         "name": "Niek",
    7.         "blog": "https://040code.github.io",
    8.         "githubAccount": "npalm",
    9.         "talks": [
    10.           {
    11.             "id": "19",
    12.             "title": "GraphQL - The Next API Language"
    13.           },
    14.           {
    15.             "id": "20",
    16.             "title": "Immutable Infrastructure"
    17.           }
    18.         ]
    19.       }
    20.     ]
    21.   }
    22. }

    In the GET request, the variables are passed in the query string.

    To disable the degraphql Plugin, you can delete the corresponding JSON configuration from the Plugin configuration. APISIX will automatically reload and you do not have to restart for this to take effect.

    1. curl http://127.0.0.1:9180/apisix/admin/routes/1  -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
    2. {
    3.   "methods": ["GET"],
    4.   "uri": "/graphql",
    5.   "plugins": {},
    6.   "upstream": {
    7.     "type": "roundrobin",
    8.     "nodes": {
    9.       "127.0.0.1:8080": 1
    10.     }
    11. }'