Quickstart#

Connect to the Playground#

Sterblue GraphQL playground is the best way to get started with the API. Just connect to https://graph.sterblue.com/ using any modern web browser, and get started. The interface should look like something like this (without tabs, for your first connection):

Screenshot

Expand the Query Variables/HTTP Headers panel#

The first thing to do here is to expand the Query Variables/HTTP Headers panel in the bottom left corner of the application. Once expanded, your screen should look like this:

Screenshot

Get Sterblue credentials#

Most of the GraphQL API is not available until you are authenticated as a user. To authenticate, you will need to perform a first GraphQL query to obtain a user token from the API.

From here, you will need valid Sterblue credentials (User email and password) for an existing user account. If you do not have a valid Sterblue credentials, please contact us to create an account (Either by email at support@sterblue.com or directly on our website messaging on https://www.sterblue.com). You should be able to connect to https://cloud.sterblue.com/ with these credentials.

Perform our first GraphQL Query: Authentication#

Once you have valid Sterblue user email and password, you can continue:

Screenshot

In the query input box (Top left part of the screen), enter the following GraphQL Query. Do not replace anything in this query, just paste it as-is:

graphql
1
mutation authenticateUser($email: String!, $password: String!) {
2
authenticateUser(email: $email, password: $password) {
3
Authorization: token
4
}
5
}

Then, in the query variables box (Bottom left part of the screen), enter the query variables as a JSON object. Please do replace the values with your Sterblue credentials:

json
1
{
2
"email":"your.name@company.com",
3
"password":"your password"
4
}

Here you defined the values of two variables email and password, which are used in the GraphQL query above.

You can now press the “Run Query Button”, the round button with the triangle icon at the center of the screen. This will run your query on Sterblue’s servers and give you a response on the right part of the screen. The response should look like this:

json
1
{
2
"data": {
3
"authenticateUser": {
4
"Authorization":"<<<AUTHORIZATION_TOKEN>>>",
5
}
6
}
7
}

The response contains your Authorization token in place of the <<<AUTHORIZATION_TOKEN>>> placeholder above. This token will allow you to access the rest of the Graph API.

Open a new tab and launch your first authenticated GraphQL query#

Open a new tab in GraphQL playground, using the “+” button next to your first tab. If necessary, expand the Http Headers panel as explained before.

Screenshot

We can now enter a GraphQL query in the query input (Top left of the screen). Let’s write a GraphQL query which asks for the ids and the file urls of the first 10 images you have access to:

graphql
1
{
2
images(first: 10) {
3
id
4
file {
5
url
6
}
7
}
8
}

Now that you have your authorization token as explained earlier, you can use it to perform authenticated queries. To perform queries as an authenticated user, just paste your Authorization token in the Http Headers Panel (Bottom left of the screen). The Http Header content should look like this:

json
1
{
2
"Authorization": "<<<AUTHORIZATION_TOKEN>>>"
3
}

You can now run the query by pressing the “Run Query Button” in the center of the screen. You should see the response appear on the right side of the screen.

In this particular query. The response contains image URLs. As a side note specifically for images, note that if you want to access the original image file, you will need to add /original.jpeg at the end of the URL returned by the API. For example, if the Graph gives you an image whose URL is https://sterblue-images.s3.eu-west-1.amazonaws.com/cjc2l4a116ccj0106g1234567/0001-DJI_0161-STERBLUE.JPG/, the link is not directly valid, but you can access the actual original image file at https://sterblue-images.s3.eu-west-1.amazonaws.com/cjc2l4a116ccj0106g1234567/0001-DJI_0161-STERBLUE.JPG/original.jpeg.

Access the interactive documentation#

Our Graph API is self-documented. You can access all the documentation in the GraphQL playground. There are several ways to benefit from the documentation:

  • Automatic autocompletion of your queries

  • Manual autocompletion of your queries, triggered by pressing CTRL-SPACE when writing a query in the query area

  • Schema documentation, using the "Schema" Button on the right side of the screen.

Here is a screenshot showcasing both Autocompletion (on the left side, in the query area), and the schema documentation (on the right side, in the sidebar). Our API is based on the principle of OpenCrud (https://github.com/opencrud/opencrud).

Screenshot