isaitb/graphql-validator repository overview

⁠Introduction

A web application to validate GraphQL against the reference GraphQL implementation⁠. Validation is possible via several channels:

• REST API for machine-to-machine integration.
• SOAP API for machine-to-machine integration and use in GITB TDL⁠ conformance test cases.

This image is maintained by the European Commission's DIGIT and specifically the Interoperability Test Bed, a conformance testing service for projects involved in the delivery of cross-border public services. Find out more here⁠.

⁠Usage

To start the validator with its default configuration issue:

docker run -d --name my-validator -p 8080:8080 isaitb/graphql-validator

Doing so will make available the validator as follows:

• REST API: http://localhost:8080/graphql/api/validate⁠
• Swagger UI: http://localhost:8080/graphql/api/docs⁠
• SOAP: http://localhost:8080/graphql/soap/validation?wsdl⁠

In terms of configuration the validator supports properties to customise how its endpoints are published.

An an example, if the validator is mapped to a 9999 host port and exposed behind a proxy as https://www.test.org/validator you would likely want to adapt the docker run command as follows:

docker run -d --name my-validator -p 9999:8080 \
             -e validator_context_path=/validator \
             -e validator_docs_host=www.test.org \
             -e validator_docs_schemes=https \
             -e validator_wsdl_endpoint=https://www.test.org/validator/soap/validation \
             isaitb/graphql-validator

In terms of using the validator you would typically do so via its REST API (documented through its Swagger UI). Using the the REST API for a typical validation you would do a POST to /api/validate with the following body:

{
	"schema": "schema { ... }",
	"query": "query myQuery { ... }"
}

You can also pass the schema and query properties as URI references instead of direct texts:

{
	"schema": "http://localhost/graphql/schema.graphql",
	"schemaEmbeddingMethod": "URI",
	"query": "http://localhost/graphql/query.graphql",
	"queryEmbeddingMethod": "URI"
}

The validator's SOAP API primarily serves to use it in GITB TDL test cases⁠. If used directly you would call it as follows (for resources provided through URIs):

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:v1="http://www.gitb.com/vs/v1/" xmlns:v11="http://www.gitb.com/core/v1/">
   <soapenv:Header/>
   <soapenv:Body>
      <v1:ValidateRequest>
    	<sessionId>123</sessionId>
	    <input name="schema" embeddingMethod="URI">
          <v11:value>http://localhost/graphql/schema.graphql</v11:value>
        </input>
	    <input name="query" embeddingMethod="URI">
          <v11:value>http://localhost/graphql/query.graphql</v11:value>
        </input>
      </v1:ValidateRequest>
   </soapenv:Body>
</soapenv:Envelope>

If used in a GITB TDL test case, you would use the validator as a custom handler for a verify step⁠, passing in the expected inputs:

<steps>
   ...
   <verify handler="http://localhost:8080/graphql/soap/validation?wsdl" desc="Validate query">
      <input name="schema">$queryToValidate</input>
      <input name="query">$schemaToUse</input>
   </verify>
   ...
</steps>

⁠Licence

This tool is shared using the European Union Public Licence (EUPL) version 1.2⁠.

⁠Legal notice

The authors of this tool waive any and all liability linked to its usage or the interpretation of its results. In terms of data, the tool does not harvest, collect or process in any way data that could be linked to the tool's user or workstation, nor does it maintain any state or statistics other than the report files that it produces as output.

⁠Contact

To get in touch for feedback or questions you are invited to send an email to [email protected]⁠.