Skip to content

Commit

Permalink
[DOCU-2349] GraphQL server path (#3960)
Browse files Browse the repository at this point in the history 
* add graphql_server_path; set up single-sourced version; minor grammar and formatting cleanup

* minor grammar edits

* set required: true for graphql_server_path

* attempt to rephrase
  • Loading branch information
@lena-larionova
lena-larionova authored Jun 14, 2022
1 parent 6e0c328 commit c0db666
Show file tree
Hide file tree
Showing 2 changed files with 136 additions and 96 deletions.
217 changes: 122 additions & 95 deletions app/_hub/kong-inc/degraphql/_index.md
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,6 @@
---
name: DeGraphQL
publisher: Kong Inc.
version: 0.1.0
desc: Transform a GraphQL upstream into a REST API
description: |
This plugin transforms a GraphQL upstream into a traditional endpoint by mapping URIs into GraphQL queries.
Expand All @@ -27,113 +26,131 @@ params:
name: degraphql
service_id: true
dbless_compatible: 'yes'
config: null
config:
- name: graphql_server_path
required: true
default: "/graphql"
datatype: string
description: The path to the GraphQL server.
minimum_version: "3.0.x"
---
## Usage

DeGraphQL needs a graphql endpoint to query. As an example, we are going to
build a REST API around https://api.github.com GraphQL service. For that reason
examples are going to include the header `Authorization: Bearer some-token`.
DeGraphQL needs a GraphQL endpoint to query. As an example, we are going to
build a REST API around the `https://api.github.com` GraphQL service. For that
reason, the following examples include the header `Authorization: Bearer some-token`.

Note this plugin differs from other plugins as far as configuration goes. It
needs to be activated on a service that points to a GraphQL endpoint
(sans `/graphql`).
This plugin must be activated on a service that points to a GraphQL endpoint.

### 1. Create a Service and a Route in Kong:
### Create a Service and a Route

```bash
$ curl -X POST http://localhost:8001/services \
--data name="github" \
--data url="https://api.github.com"
$ curl -X POST http://localhost:8001/services/github/routes \
--data paths="/api"
```
Create a Service and Route in {{site.base_gateway}}:

### 2. Configure the Plugin on the Service
```bash
curl -X POST http://localhost:8001/services \
--data name="github" \
--data url="https://api.github.com"

The plugin takes over the service. From this point on, the service represents
our REST api and not the graphql endpoint itself. It will return a 404 Not Found
if no DeGraphQL routes have been configured.
curl -X POST http://localhost:8001/services/github/routes \
--data paths="/api"
```

```bash
$ curl -X POST http://localhost:8001/services/github/plugins \
--data name="degraphql"
```
### Configure the plugin on the Service

### 3. Configure DeGraphQL Routes on the Service
Set up the DeGraphQL plugin:

Once the Plugin is activated on a Service, we can add our own routes to build
our service, by defining URIs and associating them to GraphQL queries.
```bash
curl -X POST http://localhost:8001/services/github/plugins \
--data name="degraphql"
```

```bash
$ curl -X POST http://localhost:8001/services/github/degraphql/routes \
--data uri="/me" \
--data query="query { viewer { login } }"
Enabling the plugin disables regular service function. Instead, the
plugin now builds the path and GraphQL query to hit the GraphQL service
with.

$ curl http://localhost:8000/api/me \
--header "Authorization: Bearer some-token"
{
"data": {
"viewer": {
"login": "you"
}
}
}
```

GraphQL Query Variables can be defined on URIs:

```bash
$ curl -X POST http://localhost:8001/services/github/degraphql/routes \
--data uri='/:owner/:name' \
--data query='query ($owner:String! $name:String!){
repository(owner:$owner, name:$name) {
name
forkCount
description
}
}'

$ curl http://localhost:8000/api/kong/kong \
--header "Authorization: Bearer some-token"
{
From this point on, the Service represents
your REST API and not the GraphQL endpoint itself. It will return a `404 Not Found`
status code if no DeGraphQL routes have been configured.

### Configure DeGraphQL Routes on the Service

Once the plugin is activated on a Service, you can add your own routes
by defining URIs and associating them to GraphQL queries.

{:.note}
> Don't include the GraphQL server path prefix in the URI parameter
(`/graphql` by default).

```bash
curl -X POST http://localhost:8001/services/github/degraphql/routes \
--data uri="/me" \
--data query="query { viewer { login } }"

curl http://localhost:8000/api/me \
--header "Authorization: Bearer some-token"
{
"data": {
"repository": {
"description": "🦍 The Cloud-Native API Gateway ",
"forkCount": 2997,
"name": "kong"
"viewer": {
"login": "you"
}
}
}
```


GraphQL query variables can be defined on URIs:

```bash
curl -X POST http://localhost:8001/services/github/degraphql/routes \
--data uri='/:owner/:name' \
--data query='query ($owner:String! $name:String!){
repository(owner:$owner, name:$name) {
name
forkCount
description
}
}'

curl http://localhost:8000/api/kong/kong \
--header "Authorization: Bearer some-token"
{
"data": {
"repository": {
"description": "🦍 The Cloud-Native API Gateway ",
"forkCount": 2997,
"name": "kong"
}
}
```

The same Variables can also be provided as GET arguments:

```bash
$ curl -X POST http://localhost:8001/services/github/degraphql/routes \
--data uri='/repo' \
--data query='query ($owner:String! $name:String!){
repository(owner:$owner, name:$name) {
name
forkCount
description
}
}'

$ curl "http://localhost:8000/api/repo?owner=kong&name=kuma" \
--header "Authorization: Bearer some-token"
{
"data": {
"repository": {
"description": "🐻 The Universal Service Mesh",
"forkCount": 48,
"name": "kuma"
}
}
}
```

The same variables can also be provided as `GET` arguments:

```bash
curl -X POST http://localhost:8001/services/github/degraphql/routes \
--data uri='/repo' \
--data query='query ($owner:String! $name:String!){
repository(owner:$owner, name:$name) {
name
forkCount
description
}
}'

curl "http://localhost:8000/api/repo?owner=kong&name=kuma" \
--header "Authorization: Bearer some-token"
{
"data": {
"repository": {
"description": "🐻 The Universal Service Mesh",
"forkCount": 48,
"name": "kuma"
}
}
```
}
```

### Available endpoints
## Available endpoints

**List defined DeGraphQL Routes for a service**

Expand All @@ -143,21 +160,31 @@ The same Variables can also be provided as GET arguments:

<div class="endpoint post">/services/:service_name/degraphql/routes</div>

| Attributes | Description
| Attribute | Description
| -------------- | -------
|`uri` | path to map to a GraphQL query
|`query` | GraphQL query to map to uri
|`uri` | Path to map to a GraphQL query.
|`query` | GraphQL query to map to the URI.

**Edit a DeGraphQL Route for a Service**

<div class="endpoint patch">/services/:service_name/degraphql/routes/:id</div>

| Attributes | Description
| Attribute | Description
| -------------- | -------
|`uri` | path to map to a GraphQL query
|`query` | GraphQL query to map to uri
|`uri` | Path to map to a GraphQL query.
|`query` | GraphQL query to map to the URI.


**Delete a DeGraphQL Route for a Service**

<div class="endpoint delete">/services/:service_name/degraphql/routes/:id</div>

---
{% if_plugin_version gte:3.0.x %}
## Changelog

### Kong Gateway 3.0.x

* Added the `graphql_server_path` configuration parameter.

{% endif_plugin_version %}
15 changes: 14 additions & 1 deletion app/_hub/kong-inc/degraphql/versions.yml
View file
Original file line number Diff line number Diff line change
@@ -1 +1,14 @@
- release: 1.3-x
strategy: gateway
delegate_releases: true

overrides:
3.0.x: 0.2.0
2.8.x: 0.1.2
2.7.x: 0.1.2
2.6.x: 0.1.2
2.5.x: 0.1.2
2.4.x: 0.1.2
2.3.x: 0.1.2
2.2.x: 0.1.2
2.1.x: 0.1.2
2.0.x: 0.1.2

0 comments on commit c0db666

Please sign in to comment.