Writing Queries

This document explains how to write and execute GraphQL queries and mutations for QueryBoost.

Queries in QueryBoost use regular GraphQL syntax. QueryBoost follows some conventions to make writing queries easier.

Conventions

NameSpacing

Namespacing separates the GraphQL schema by source. This prevents any type clashes and tells QueryBoost which source to execute your query on.

In this example, we are querying for customers on the Stripe source:

loading...

You can find available namespaces and queries by using the schema documentation. The easiest method is using the Explorer or Documentation in the Sandbox.

Case Styles

QueryBoost uses camelCase for all field names, even if the source API uses snake_case or some other case style.

Pagination

QueryBoost transforms pagination from each source API into a common format.

Inputs

If a query can return paginated data, it will accept the pagination input argument. This argument takes:

  • For cursor based pagination
    • endingBefore - get data ending before this cursor
    • startingAfter - get data starting after this cursor
  • For offset based pagination
    • limit - limit the number of records returned
    • offset - offset the number of records returned by this amount

Outputs

Queries that return paginated data, also provide the `pageInfo` object. This object returns:
  • endCursor - the cursor for the last record in the returned page
  • startCursor - the cursor for the first record in the returned page
  • hasMore - true if there are additional records to fetch
  • totalRecords - the number of records returned in this page

You should use the arguments for the pagination type that the source API has implemented.

loading...

Helpers

Date Formatting

You can specify the format of any datetime field directly in your query or mutation.

Any field that returns a datetime will provide a format argument. This argument accepts a string denoting how you want the date to be formatted. QueryBoost will convert any timestamp or date into this format and then return the result. See References for a full set of possible format strings.

QueryBoost also converts date input fields into the correct format for the source API. For example if the source API accepts unix timestamps, you can provide a date 2020-01-18 and QueryBoost will convert this to a timestamp before calling the source API.


loading...

Execute Requests

Requests consist of:

  • a body containing the GraphQL query or mutation
  • the url of the endpoint
  • your API Key in the Authorization Header

Endpoint

QueryBoost uses a single endpoint for all requests. The data returned will depend on the API key that you include in the request. The endpoint for QueryBoost is:

https://api.queryboost.com

If you want to get Mock Data back for development or testing purposes, you should send your request to:

https://api.queryboost.com/mocks

API Keys

Your account has two API Keys:

  • Live - the live api key will query your connected sources and return real data

  • Test - The test api key will return mock data. It should be used with mock end point.

Your API Keys are available on the Developer page.

Sandbox

The interactive Sandbox provides a quick method of building queries. It also let's you browse the schema documentation and has autocomplete and error checking for fields and inputs.