Getting started

Overview

As discussed in the introduction, Sanctuary Health provides a JSON data via a GraphQL API. As GraphQL is a query language for APIs this means any data request is comprised of two parts:

• Communicating with the API
• Requesting the required data via GraphQL

Communicating with the API

Communication with the Sanctuary Health API is handled by simple HTTP POST queries to https://v4-0-dot-livitay.appspot.com/graphql. This allows easy communication with all programing languages.

Authentication

When communicating with the Sanctuary Health API it is important that you provide your organizations API key. While your API key is used to provide access to the data, it is also used to narrow results to your organization's selected content so the correct data is returned. Your API key should be provided in the headers of the HTTP request using the key apikey.

info

Your organization's API key can be found in the API Details tab of the Account page on the content dashboard https://app.sanctuaryhealth.io/account?tab=api+details

caution

Throughout this documentation the DEMO API key 9677bbd3-4b5b-4a2f-a085-201771d6ad9c is used. When copying queries be sure to update this to get the expected results as this is a common issue.

Example

headers: {
    "Content-Type": "application/json",
    "apikey": "9677bbd3-4b5b-4a2f-a085-201771d6ad9c"
},

Requesting the required data via GraphQL

To request the required data from the Sanctuary Health API, a GraphQL query and any query variables for the query, must be provided in the body of the HTTP query as a string of JSON data. The JSON data should be an object with the query provided as a string with the query key and the variables being provided as a JSON object at the variables key. Building these queries will be the main focus of this documentation, with a full reference of queries, data objects etc. is available in the Reference section.

In this example we will use a getPosts query and set the variables such that only c4cf717d-a638-49d8-bbcd-fafd2142d284 is returned.

Example

body: JSON.stringify({
    "query": "query gettingStarted($sequelizeQuery: SequelizeQuery) {
        getPosts(sequelizeQuery: $sequelizeQuery) {
            id
            title
        }
    }",
    "variables": {
        "sequelizeQuery": {
            "where": '{ "id": "c4cf717d-a638-49d8-bbcd-fafd2142d284" }'
        }
    }
})

Putting it all together

The following example is written in Javascript however it should be fairly easy to update to your programing language of choice. Feel free to copy the below code into your browser console to test it out.

fetch("https://v4-0-dot-livitay.appspot.com/graphql", {
    method: "POST",
    headers: {
        "Content-Type": "application/json",
        apikey: "9677bbd3-4b5b-4a2f-a085-201771d6ad9c"
    },
    body: JSON.stringify({
        query: `query gettingStarted($sequelizeQuery: SequelizeQuery) {
            getPosts(sequelizeQuery: $sequelizeQuery) {
                id
                title
            }
        }`,
        variables: {
            sequelizeQuery: {
                where: '{ "id": "c4cf717d-a638-49d8-bbcd-fafd2142d284" }'
            }
        }
    })
})
    .then((response) => response.json())
    .then((data) => console.log(data))

Next steps

Now that we have walked through how to communicate with the API, as promised it is time to start looking deeper into the building queries and learning how we can access the data we want.

Furthermore while the above example can be used to fetch data and can be adjusted for any programing language it is verbose and difficult to work with. Given that GraphQL is strongly typed there is a number of helpful tools to make our life easier, ranging from IDEs all the way to code generation tools. Please view our implementation recommendations for more information, or our full guide for a full worked tutorial of all our recommended tools.