Introduction to SportsEngine API
Welcome to the SportsEngine API, which enables your organization's applications to get data to and from SportsEngine. This article will guide you through:
Authenticating with the SportsEngine Platform
Working with GraphQL
Understanding available data
What is GraphQL?
Graph Query Language [GraphQL] is a modern technology created by Netflix and Facebook. It will only return data attributes you request to avoid navigating multiple endpoints and pass various IDs to every service to get a complete picture of one person, like a Traditional REST API.
GraphQL only returns the data attributes you request, drastically decreasing the data returned and the response time.
There are two primary areas of GraphQL:
Queries: Allow data out of the platform.
Mutations: Allow data creation, editing, or deletion from the platform.
To learn more about GraphQL, visit How to GraphQL for additional information and video tutorials.
Authentication
The SportsEngine Platform implements OAuth2 for accessing GraphQL and follows the standard authorization workflows. Learn more about the different workflows for your application and how organizations permit you to access their data with our Authenticating with SportsEngine article.
Schema Documentation & Tools
Visit https://dev.sportsengine.com/explorer to find Schema documentation and information for building and testing queries. The primary objects available include:
Organizations
Profiles
Teams
Events
Registrations
Keep an eye out for more primary object additions soon!
The SportsEngine GraphQL API supports schema introspection for API tools. This enables schemas to be easily downloaded to applications like Postman or Insomnia by connecting with the GraphQL API endpoint. Follow the steps below to get started with an API tool:
Complete the authentication process.
Create a GraphQL API query in the API tool.
Copy your access token into the tool's authorization section as a bearer token.
Set the tool's request URL to https://api.sportsengine.com/graphql.
SportsEngine API will pull the schema into the tool.
If not using an API tool, enter the query in the GraphiQL interface here and include the following Authorization header. Note that all requests to GraphQL are POST.
Content-Type: application/json
Host: api.sportsengine.com
Authorization: Bearer {{access-token}}
Request Limits
All queries have a complexity score to prevent queries from being too complex and consuming too much time. Determining how many separate internal API calls are involved in a query will calculate a complexity score.
Queries with complexity scores that are too high are rejected and return a "Query is too complex" error.
{
"errors": [
{
"message": "Query is too complex: 201. Maximum allowed complexity: 101",
"extensions": {
"code": "INTERNAL_SERVER_ERROR"
}
}
]
}
The easiest way to reduce complexity is to reduce the page size. If that is not feasible, you must remove attributes from the query that directly increase complexity. Please refer to the schema documentation for the attributes that increase complexity.
Date & Time Zone Formatting
All date and time attributes in the SportsEngine GraphQL API are in UTC format (YYYY-MM-DDThh:mm:ss.SSSZ).
More Resources
You made it and are ready to get started with queries and mutations. You can learn more with community forums HERE.