Quantum API

The Quantum API is built on GraphQL, a query language that allows clients to interact with Quantum datasets and query for exactly what they need and nothing more.

HTTP API Overview

An HTTP REST API is provided that supports authentication, user management, and GraphQL access.

• The root of this REST API is https://quantumalliance.org/api/
• Detailed interactive documentation for all operations is available at https://quantumalliance.org/app/swagger/.

Logging In

The GraphQL API endpoints by default use JSON Web Token (JWT) authorization, which ensures that a client has logged into the system before making changes or requesting data.

In order to retrieve a JWT, clients should make a GET request with basic authentication to https://quantumalliance.org/api/auth/login.

For example, from a Unix command line:

curl -u user:password --basic https://quantumalliance.org/api/auth/login

This will respond with a JSON object that contains authorization and refresh tokens. The authorization token should be included in requests to the Quantum API.

Generating API Keys

The Quantum API endpoints additionally support the use of API keys, which can be generated with an authenticated request.

For example, from a Unix command line:

		
			curl -X 'POST' \

		 	-H ‘X-PL-AUTH: <TOKEN>‘ \

			https://quantumalliance.org/api/auth/api-key/generate
		
	

This will respond with a JSON object containing an API key linked to the user making the request along with its expiration time. API Keys act with the same permissions as a JWT for the user who generated them would, but provide a longer-lived and more convenient use pattern for command-line and scripting purposes.

Querying with GraphQL

Once an authorization token has been retrieved or API key generated, GraphQL queries can be requested from https://quantumalliance.org/api/graphql.

For example, to query all the sites and their names using an authorization JWT:

	 	curl -X 'POST' \

		  'https://quantumalliance.org/api/graphql' \

		  -H 'accept: application/json' \

		  -H ‘X-PL-AUTH: <TOKEN>' \

		  -H 'Content-Type: application/json' \

		  -d '{"query": "query { sites { name } }”}'
		
	 

Or, the same query using an API Key:

		
			curl -X 'POST' \

		  'https://quantumalliance.org/api/graphql' \

		  -H 'accept: application/json' \

		  -H 'Authorization: PL-API-KEY <KEY>' \

		  -H 'Content-Type: application/json' \

		  -d '{"query": "query { sites { name } }”}'
		
	

The GraphQL API supports GET and POST request formats. Support for GraphQL subscriptions is available through the https://quantumalliance.org/api/graphqlSubscribe endpoint, which will open a WebSocket. See the Quantum API documentation for more details.

Interactive documentation of the Quantum GraphQL type system is available in the Quantum Explorer app. Users can see what types are available in the API, their specific attributes, and their relationship with other types. This information may also be queried directly from the Quantum API using introspection queries.