Skip to content

Commit

Permalink
Add Bearer Token Authorization & customHeaders docs (#43)
Browse files Browse the repository at this point in the history 
* Cleanup & Docs

* scorecard changes

* update versions
  • Loading branch information
@rgstephens
rgstephens authored Dec 10, 2022
1 parent 1b612a4 commit 3a1e1f0
Show file tree
Hide file tree
Showing 18 changed files with 300 additions and 473 deletions.
82 changes: 41 additions & 41 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,22 +3,16 @@
[![Platform](https://img.shields.io/badge/platform-Node--RED-red)](https://nodered.org)
![Release](https://img.shields.io/npm/v/node-red-contrib-graphql.svg)
![NPM](https://img.shields.io/npm/dm/node-red-contrib-graphql.svg)
[![Codacy Badge](https://api.codacy.com/project/badge/Grade/6cbeb40ab5604b3ab99e6badc9469e8a)](https://www.codacy.com/gh/rgstephens/node-red-contrib-graphql?utm_source=github.com&utm_medium=referral&utm_content=rgstephens/node-red-contrib-graphql&utm_campaign=Badge_Grade)

A NodeRed node to execute GraphQL Queries.

## Install

Run command on Node-RED installation directory.

```
npm install node-red-contrib-graphql
```

## Change Log

| Vers | Changes |
| ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 2.0.1 | Update dependencies (`axios` & `mustache`), fix node-red scorecard issues |
| 2.1.0 | Bearer Token Authentication |
| 2.0.1 | Update dependencies (`axios` & `mustache`), fix node-red scorecard issues |
| 2.0.0 | GraphQL response is now on `payload.graphql` instead of replacing `payload`. This is a breaking change. Addresses #32 |
| 1.4.1 | Bump `follow-redirects` to 1.14.8 |
| 1.4.0 | improve debug, bump `follow-redirects` |
Expand All @@ -30,15 +24,15 @@ npm install node-red-contrib-graphql

## GraphQL Nodes

Provides a `GraphQL` node to support queries and a supporting Configuration node, called `graphql-server` to point to a GraphQL server.
Provides a `GraphQL` node to support queries and a configuration node called `graphql-server`.

### `graphql-server` Configuration Node Fields

| Name | Use |
| ------------- | ------------------- |
| Name | Node Name |
| Endpoint | URL to the endpoint |
| Authorization | Header |
| Name | Use |
| -------- | ------------------- |
| Name | Node Name |
| Endpoint | URL to the endpoint |
| Token | Bearer Token |

### `graphql` Function Node Fields

Expand All @@ -48,46 +42,52 @@ Provides a `GraphQL` node to support queries and a supporting Configuration node
| Endpoint | Configuration Node Name |
| Query | Query or Mutation template |
| Syntax | Mustache / plain |
| Token | Bearer Token |
| Show Debug | Enable debug |

## Installing and using the Example Flow
## Countries API Example

This example flow uses the `node-red-contrib-graphql` node to query the Deutsche Bahn GraphQL service and get a station address and details on the next departure.
This example flow uses the `node-red-contrib-graphql` node to query the [Countries API](https://github.com/trevorblades/countries) built by GitHub user [Trevor Blades](https://github.com/trevorblades).

The example flow is in the file `countries.json`. Import this file from the clipboard under the NodeRed menu `Import > Clipboard`. You'll drag the example flow onto NodeRed.
The example flow is in the file `examples/countries.json`. Import this file from the clipboard under the NodeRed menu `Import > Clipboard`. You'll drag the example flow onto NodeRed.

![Example Flow](flow.png)
![Example Flow](images/flow.png)

### Edit graphql node

The GraphQL endpoint for is `https://countries.trevorblades.com/`. You can try it out [here](https://countries.trevorblades.com/). Here's the `graphql-node`:

![Edit GraphQL Node](images/editGraphQL.png)

### GraphQL Output

This is the result sent to the debug window.

![Example Flow Output](flowOutput.png)
![Example Flow Output](images/flowOutput.png)

### Countries API
## Authentication Example

Here is the example using the [Countries API](https://github.com/trevorblades/countries) built by GitHub user [Trevor Blades](https://github.com/trevorblades), who used [Countries List](https://annexare.github.io/Countries/) as a source of data.
A bearer token can be provided for authentication. This is an example using the GitHub GraphQL API which is documented [here](https://docs.github.com/en/graphql/guides/forming-calls-with-graphql#communicating-with-graphql).

The GraphQL endpoint for this API is `https://countries.trevorblades.com/`. You can try it out [here](https://countries.trevorblades.com/).
![Github Flow](images/githubFlow.png)

```json
# Get information on Germany and it's states
{
country(code: "DE") {
name
native
capital
currency
phone
states {
code
name
}
}
}
```
### Config Node Token

If you have an token with a long life, you can provide the token in the `graphql-server` configuration node. For GitHub, user your GitHub PAT.

![Github Config](images/githubGraphqlConfig.png)

You can also provide the token in the `graphql` node. This is useful if a prior node performs the authentication and returns the token to be used for a limited session.

![GitHub GraphQL](images/githubGraphql.png)

## Custom Headers

You can provide custom headers to the GraphQL node by attaching a `customHeaders` key to the `msg` and passing that to the GraphQL node. Here's an example that sets the `content-type` and a bearer token.

![Edit GraphQL Node](editGraphQL.png)
![Custom Headers](images/customHeaders.png)

## Template flavors and uses
## Templates and Variable Use

There are two template flavors:

Expand Down
Binary file removed editGraphQL.png
View file
Binary file not shown.
Binary file removed editGraphQLserver.png
View file
Binary file not shown.
111 changes: 110 additions & 1 deletion examples/countriesFlow.json
View file
Original file line number Diff line number Diff line change
@@ -1 +1,110 @@
[{"id":"a12eeec2ef7081f3","type":"graphql","z":"e596e2e15cffe546","name":"Get Country","graphql":"5ec8b7409ad68ba9","format":"json","syntax":"mustache","template":"{\n country(code: \"DE\") {\n name\n native\n capital\n currency\n phone\n states {\n code\n name\n }\n }\n}","showDebug":false,"x":290,"y":80,"wires":[["b1909e0fe42ed002","b4a00ddbf587d5db"],["b4a00ddbf587d5db"]]},{"id":"8ce305107f24099c","type":"inject","z":"e596e2e15cffe546","name":"","props":[{"p":"payload"},{"p":"topic","vt":"str"}],"repeat":"","crontab":"","once":false,"onceDelay":0.1,"topic":"","payload":"","payloadType":"date","x":100,"y":80,"wires":[["a12eeec2ef7081f3"]]},{"id":"b4a00ddbf587d5db","type":"debug","z":"e596e2e15cffe546","name":"","active":true,"tosidebar":true,"console":false,"tostatus":false,"complete":"true","targetType":"full","statusVal":"","statusType":"auto","x":490,"y":100,"wires":[]},{"id":"b1909e0fe42ed002","type":"template","z":"e596e2e15cffe546","name":"Country Details","field":"payload","fieldType":"msg","format":"handlebars","syntax":"mustache","template":"Country Name - {{payload.graphql.country.name}} / {{payload.country.native}}\nCapital: {{payload.graphql.country.capital}}\nCurrency: {{payload.graphql.country.currency}}\nStates:\n {{payload.graphql.country.states.0.name}}\n {{payload.graphql.country.states.1.name}}\n {{payload.graphql.country.states.2.name}}\n {{payload.graphql.country.states.3.name}}\n","output":"str","x":520,"y":60,"wires":[["080fbc2ad4668f85"]]},{"id":"080fbc2ad4668f85","type":"debug","z":"e596e2e15cffe546","name":"","active":true,"tosidebar":true,"console":false,"complete":"false","statusVal":"","statusType":"auto","x":730,"y":60,"wires":[]},{"id":"5ec8b7409ad68ba9","type":"graphql-server","name":"Countries","endpoint":"https://countries.trevorblades.com"}]
[
{
"id": "a12eeec2ef7081f3",
"type": "graphql",
"z": "e596e2e15cffe546",
"name": "Get Country",
"graphql": "5ec8b7409ad68ba9",
"format": "json",
"syntax": "mustache",
"template": "{\n country(code: \"DE\") {\n name\n native\n capital\n currency\n phone\n states {\n code\n name\n }\n }\n}",
"showDebug": false,
"x": 290,
"y": 80,
"wires": [
[
"b1909e0fe42ed002",
"b4a00ddbf587d5db"
],
[
"b4a00ddbf587d5db"
]
]
},
{
"id": "8ce305107f24099c",
"type": "inject",
"z": "e596e2e15cffe546",
"name": "",
"props": [
{
"p": "payload"
},
{
"p": "topic",
"vt": "str"
}
],
"repeat": "",
"crontab": "",
"once": false,
"onceDelay": 0.1,
"topic": "",
"payload": "",
"payloadType": "date",
"x": 100,
"y": 80,
"wires": [
[
"a12eeec2ef7081f3"
]
]
},
{
"id": "b4a00ddbf587d5db",
"type": "debug",
"z": "e596e2e15cffe546",
"name": "",
"active": true,
"tosidebar": true,
"console": false,
"tostatus": false,
"complete": "true",
"targetType": "full",
"statusVal": "",
"statusType": "auto",
"x": 490,
"y": 100,
"wires": []
},
{
"id": "b1909e0fe42ed002",
"type": "template",
"z": "e596e2e15cffe546",
"name": "Country Details",
"field": "payload",
"fieldType": "msg",
"format": "handlebars",
"syntax": "mustache",
"template": "Country Name - {{payload.graphql.country.name}} / {{payload.graphql.country.native}}\nCapital: {{payload.graphql.country.capital}}\nCurrency: {{payload.graphql.country.currency}}\nStates:\n {{payload.graphql.country.states.0.name}}\n {{payload.graphql.country.states.1.name}}\n {{payload.graphql.country.states.2.name}}\n {{payload.graphql.country.states.3.name}}\n",
"output": "str",
"x": 520,
"y": 60,
"wires": [
[
"080fbc2ad4668f85"
]
]
},
{
"id": "080fbc2ad4668f85",
"type": "debug",
"z": "e596e2e15cffe546",
"name": "",
"active": true,
"tosidebar": true,
"console": false,
"complete": "false",
"statusVal": "",
"statusType": "auto",
"x": 730,
"y": 60,
"wires": []
},
{
"id": "5ec8b7409ad68ba9",
"type": "graphql-server",
"name": "Countries",
"endpoint": "https://countries.trevorblades.com"
}
]
95 changes: 0 additions & 95 deletions examples/deutscheBahnFlow.json
View file

This file was deleted.

Loading

0 comments on commit 3a1e1f0

Please sign in to comment.