Getting Started with the Sentera GraphQL API

link Introduction

The public Sentera API is implemented using GraphQL, a query language for APIs. If you are not familiar with GraphQL, this site is a nice starting point for learning about it. GraphQL.com also has some links to tutorials. We use GraphQL's type system and schema to describe our object model. You can learn more about this type system and schema here. Our generated GraphQL Schema documentation follows this convention.

link GraphQL API Requests via HTTP

GraphQL supports making requests over HTTP using the GET and POST verbs. By using standard HTTP 1.1 requests and responses, one can start using GraphQL today with existing tools and libraries. GraphQL queries are relatively simple to create and execute using standard HTTP tools.

link Single GraphQL Endpoint

api.sentera.com/graphql

Typically GraphQL APIs utilize a single endpoint for queries and mutations, and the Sentera GraphQL API is no different. We use the standard /graphql URI. All requests should be sent to api.sentera.com/graphql, regardless of query or type of resource you are interested in returning.

link Content Type for GraphQL API Requests

A GraphQL query can be sent to the server-side in a variety of content-types. A GraphQL query or mutation is an opaque string, so it can be easily sent to the server-side via the application/x-www-form-urlencoded Content-Type header. It can also be included in a simple JSON document and sent to the server-side via the application/json Content-Type header.

link Authorization for GraphQL API Requests

GraphQL requests require the user to provide a Sentera auth_token in an Authorization header, as part of a bearer authentication scheme. Please refer to Sentera's Authentication and Authorization documentation for details on obtaining a token.

link Putting It All Together

Here's an example curl command that queries for a list of fields:
curl --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer abc123' \
  --data '{ "query": "query fields { fields (pagination: { page: 1 page_size: 30 }) { total_count results { name } } }"}' \
  https://api.sentera.com/graphql
  

And the response:
{
  "data": {
    "fields": {
      "total_count": 1,
      "results": [
        { "name": "Southwest Corner" }
      ]
    }
  }
}
  

This introduction should give you a basic feel for how Sentera's GraphQL endpoint can be used. Using this information and the additional details and schema in this documentation, users should be able to leverage the powerful capabilities of Sentera's GraphQL API.