README.md

ReGraphQL

A simple (yet effective) GraphQL to REST / HTTP router.

ReGraphQL helps you expose your GraphQL queries / mutations as REST / HTTP endpoints. Doing this has the following benefits:

• Queries are stored and controlled server side. No queries on the frontend.
• Can modify and optimise your queries on demand without redoploying your (frontend) clients
• Can use GET (HTTP Method) instead of GraphQL's POST
• It's an OSS alternative to Kong's DeGraphQL

It helps you going...

From this

query($person: StarWarsPeople!) {
	getPerson(person: $person) {
		birthYear
		eyeColors
		films {
			title
		}
		gender
		hairColors
		height
		homeworld {
			name
		}
		mass
		name
		skinColors
		species {
			name
		}
		starships {
			name
		}
		vehicles {
			name
		}
	}
}

To

GET /persons/{person}

Index

• Requirements
• Features
• Service Endpoints
• Quick start
• Docker Image
• Contributing
• License
• Author

Requirements

• Go 1.18

Features

• Maps HTTP params to GraphQL Variables
• Forwards HTTP headers to GraphQL request
• Set HTTP Status Code different to 200 if GraphQL query fails.
• Hide GraphQL Error's Locations
• Hide GraphQL Error's Stacktrace
• Hide GraphQL Error's Path
• Reads configuration from .env file
• Reads configuration from environment variables
• Logs using Kubernetes' klog v2
• Docker Image below 20MB
• Exposes metrics using Prometheus
• Exposes Liveness, Readiness and Startup Probes

Service Endpoints

Liveness

GET /health/liveness

{"hostname":"pod_67804","status":"up"}

Returns HTTP Status Code OK (200) with the following JSON as soon as the application starts

{"hostname":"<< hostname >>","status":"up"}

Readiness

GET /health/readiness

{"hostname":"pod_67804","status":"ready"}

1. If the application is Ready to receive requests

Returns HTTP Status Code OK (200) with the following JSON:

{"hostname":"<< hostname >>","status":"ready"}

2. If the application is Not Ready to receive requests

Returns HTTP Status Code Precondition Failed (412) with the following JSON:

{"hostname":"<< hostname >>","status":"waiting"}

Metrics

The service exposes a Prometheus metrics endpoint at /metrics

GET /metrics

# HELP go_gc_duration_seconds A summary of the pause duration of garbage collection cycles.
# TYPE go_gc_duration_seconds summary
go_gc_duration_seconds{quantile="0"} 0
go_gc_duration_seconds{quantile="0.25"} 0
go_gc_duration_seconds{quantile="0.5"} 0
go_gc_duration_seconds{quantile="0.75"} 0
go_gc_duration_seconds{quantile="1"} 0
go_gc_duration_seconds_sum 0

Quick start

1. Describe a route in a file using yaml, which matches your HTTP endpoint with your GraphQL endpoint and Query

routes:
    - http:
          uri: '/persons/{person}'
          method: GET
      graphql:
          endpoint: 'https://swapi.skyra.pw/'
          query: |
              query($person: StarWarsPeople!) {
                  getPerson(person: $person) {
                      birthYear
                      eyeColors
                      films {
                          title
                      }
                      gender
                      hairColors
                      height
                      homeworld {
                          name
                      }
                      mass
                      name
                      skinColors
                      species {
                          name
                      }
                      starships {
                          name
                      }
                      vehicles {
                          name
                      }
                  }
              }

File starwars.yml

2. Copy starwars.yml into /tmp/config

3. Run the service (using Docker Compose)

[sudo] docker-compose up

4. Query your new HTTP endpoint!

curl 'http://127.0.0.1:8080/graphql/persons/lukeskywalker' --compressed

Docker Image

Docker image is based on Google's Distroless. The final image is around 11.2MB and packs only the necessary things to run the service.

docker pull eaceto/regraphql:latest

Contributing

Before contributing to ReGraphQL, please read the instructions detailed in our contribution guide.

License

ReGraphQL is released under the MIT license. See LICENSE for details.

Author

Created by Ezequiel (Kimi) Aceto.