GraphQL 360 Logo
GraphQL 360 Logo

Accessing GraphQL360

Endpoint

Unlike REST which uses HTTP verbs and paths to control what resources are accessed, GraphQL uses a single endpoint to access the API. The GraphQL endpoint for GraphQL360 is https://graphql360.com/graphql

Access Control

GraphQL360 requires an API key for any of the Mutations, and some of the Queries (such as those that allow you to enumerate all of your tours). You can get your api key from https://graphql360.com/keys

Supplying the api key to the endpoint is done with the x-api-key header.

Getting Started

First Query

Let's start with a simple query that gets the default location for the tour, and returns the associated image url and links other locations that the are connected to this one. We'll go into creating these links later on in the documentation.

query tourById($id: $ID) {
	tour(id: $id) {
		defaultLocation {
		  image {
	      url
		  }
			links {
				target {
					id
					name
				}
			}
		}
	}
}

When executed the above query will return something like the following:


{
	"data" : {
		"tour": {
			"defaultLocation": {
				"image": {
					"url": "https://image-cdn-example/pano.png"
				}
				"links" : {
					"id": "1234",
					"name": "Kitchen"
				}
			}
		}
	}
}

There are many ways execute this query and return the information. Items like react-apollo have all the bells and whistles of caching built in.

Alternatively the API can be queried with something as simple as fetch. For example:

const fetch = require("node-fetch")

const variables = {
   id: "<tourId>",
}

let res = await fetch("https://graphql360.com/graphql", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ query, variables }),
    }).catch(err => console.error(err))
let json = await res.json()

GraphQL360 Components

Understanding the terminology that we have picked for our API will help make it easy to navigate the graph.

Tours

Tour is the top level holder for collection of linked Locations. In addition to the list of locations it also holds information about the default or starting location. The camera rotation and metadata about the tour itself such as name and description.

Locations

A Location is the primary unit within GraphQL360. It has a one-to-one relationship with a Panorama and has a collection of Links and Tags

Each Location has an associated position (XYZ) and rotationOffset. The XYZ position of the Location helps enable automatic linking (as discussed below). The rotation offset is important to allow the panoramas to be aligned so that when you jump from one to another you feel like you are facing in the right direction.

Links

A Link is a connection between the current location and another location. Links are intended to be displayed within a given Location. As such the have Spherical Coordinates that indicate where they should be displayed.

Spherical Coordinates are little confusing when first approached, however they're the best and most consistent way of storing the Links and Tags. Each Location is a Sphere, and we can therefore refer to the position of the Links and Tags by their position on this sphere.

We have 3 values to consider. The azimuthAngle, inclinationAngle and the radialDistance.

When positioning the objects it is easiest to think of it in terms of the camera or user being the point of origin. We then rotate around the up(Y) axis, this is the azimuthAngle. The next step is then to rotate upward or downward using the inclination angle, giving us the ability to represent things that are not on the ground plane.

Finally radialDistance it the distance that the object is away from us. This can be important to allow representation of Locations that are further away but you still want to allow direct jumps to.

GraphQL360 supports both manual and automatic linking. In the case of manual linking, the Spherical Coordinates of the Link can be specified manually. In the case of Automatic Linking the link can be inferred from the XYZ position of the Location.

Tags

While a Link is a reference to another Location a Tag is an media item to display within the the current location. For example, a description of an item within the location.

Like Links they use Spherical Coordinates to describe their rotation and position within the location.

Further Resources

GraphQL360 API Docs

For further information about specific arguments and please see the API Docs. The GraphQL API has been carefully documented to allow understanding how it is all linked together. You can see the API Docs here.

Sample Applications

In addition to the documentation there are sample applications that will help you get started with consuming the API and building something in your chosen language and platform. All of the samples are store in the GraphQL360 GitHub organization.

GraphQL Playground

GraphQL360 hosts a version of GraphQL playground at /graphql. You will need to add the x-api-key header in order to interact with it. The API can be found by signing up (it's free).

GraphQL Resources

The following are useful additional GraphQL resources that can help get started in a variety of languages