The [GoTab Graph API] (reference) is a flexible query language that allows you to return as much or as little data as you need. It's important to know that GraphQL is an application layer that parses the query you send it and returns data accordingly.
Unlike [REST APIs] (reference) where there are multiple endpoints returning different data, GraphQL always exposes one endpoint
https://gotab.io/api/graphand allows you to determine the structure of the returned data.
GraphQL Reference
We are working to update our GraphQL API formatting on readme.com. While their explorer and documentation for GraphQL is in beta please also reference our schema on Apollo .
GraphQL Basics
GraphQL relies on a type system, where each object is a type and contains fields that define it. These fields can be scalars (Int, Boolean, String, etc.) or can be objects themselves. Some fields also take arguments, which can be used to limit, filter, or sort the data that is returned.
When you make a query, you define what objects (and fields) you want to return. If you're returning an object that itself contains other fields, you need to define what data you want to return on that nested object.
The remainder of this document will explore the components that make up the GoTab Graph API.
Operations
GoTab supports the query operation and the result of each query will be formatted in the same way as the query itself.
query {
locationsList {
name
locationUuid
}
}
{
"data": {
"locationsList": [
{
"name": "Demo Cafe",
"locationUuid": "6k_tKMEbg6TuLun4xAdiEJ5Z"
},
]
}
}
Query
A query performs the READ operation and does not change or alter any data.
Just like the example above, below is a query to get a list of the locations that a user has access to that your API credentials will also have access to.
query ($userId: BigInt ) {
user: userByUserId (userId: $userId ) {
locationsList {
name
locationUuid
}
}
}
curl -L -X POST 'https://gotab.io/api/v2/graph' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoicG9zdGdyYXBoaWxlX3RydXN0ZWQiLCJ1c2VyX2lkIjoiMTYxNzciLCJpYXQiOjE2NDk5NTIyOTMsImV4cCI6MTY1MDAzODY5MywiYXVkIjoicG9zdGdyYXBoaWxlIiwiaXNzIjoicG9zdGdyYXBoaWxlIn0.6CoKGXHEv76ibJY5M6ihDRJGjjhwnwP39k_rOqt73AU' \
-H 'Content-Type: application/json' \
-H 'Cookie: heroku-session-affinity=AECDaANoA24IAWEJWvX///8HYgAOh+ViAA7mtWEEbAAAAANtAAAABXdlYi4ybQAAAAV3ZWIuM20AAAAFd2ViLjFqJjR8ha4Y+4UCK4kZ5AEvMSsJk7w_' \
--data-raw '{"query":"query ($userId: BigInt ) {\n user: userByUserId (userId: $userId ) {\n locationsList {\n name\n locationUuid\n }\n }\n}","variables":{"userId":""}}'
Object Types
Object types are a collection of fields, which are used to describe the set of possible data you can query using the API.
Fields
Fields specify certain properties of objects.
Each object contains fields that can be queried by name to retrieve specific properties of the object.
query($locationUuid: String! ) {
location(locationUuid: $locationUuid ) {
spotsList {
name
spotUuid
urlName
zoneId
}
}
}
curl -L -X POST 'https://gotab.io/api/v2/graph' \
-H 'Authorization: Bearer Token' \
-H 'Content-Type: application/json' \
--data-raw '{"query":"query Query($locationUuid: String! ) {\n location(locationUuid: $locationUuid ) {\n spotsList {\n name\n spotUuid\n urlName\n zoneId\n }\n }\n }\n \n","variables":{"locationUuid":"6k_tKMEbg6TuLun4xAdiEJ5Z"}}'
Arguments
You can pass arguments in a query to determine the returned data (i.e. filtering the search results) and to narrow down the results to only the specific ones you’re after.
In the following example, we are requesting a list of orders for specific locationId. We want to filter only DELIVERED orders for a specific data range. In addition, we want to see what items were on the order that were not voided or comped.
query {
ordersList(
condition: {
locationId: "locationId"
status: DELIVERED
}
filter: {
fiscalDay: {
greaterThanOrEqualTo: "11-01-2021"
lessThanOrEqualTo: "11-05-2021"
}
}
) {
locationId
status
fiscalDay
itemsList(filter: {status: {notEqualTo: VOIDED}, comped: {equalTo: false}}) {
name
dispatched
}
}
}
curl -L -X POST 'https://gotab.io/api/v2/graph' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoicG9zdGdyYXBoaWxlX3RydXN0ZWQiLCJ1c2VyX2lkIjoiMTYxNzciLCJpYXQiOjE2NDk5NTIyOTMsImV4cCI6MTY1MDAzODY5MywiYXVkIjoicG9zdGdyYXBoaWxlIiwiaXNzIjoicG9zdGdyYXBoaWxlIn0.6CoKGXHEv76ibJY5M6ihDRJGjjhwnwP39k_rOqt73AU' \
-H 'Content-Type: application/json' \
-H 'Cookie: heroku-session-affinity=AECDaANoA24IAWEJWvX///8HYgAOh+ViAA7mtWEEbAAAAANtAAAABXdlYi4ybQAAAAV3ZWIuM20AAAAFd2ViLjFqJjR8ha4Y+4UCK4kZ5AEvMSsJk7w_' \
--data-raw '{"query":"query {\n ordersList(\n condition: {\n locationId: \"locationId\"\n status: DELIVERED\n }\n filter: {\n fiscalDay: {\n greaterThanOrEqualTo: \"11-01-2021\"\n lessThanOrEqualTo: \"11-05-2021\"\n }\n }\n ) {\n locationId\n status\n fiscalDay\n itemsList(filter: {status: {notEqualTo: VOIDED}, comped: {equalTo: false}}) {\n name\n dispatched\n }\n }\n}","variables":{"locationId":"123"}}'
Variables
Variables can be used to pass dynamic values to your arguments. Variables are written outside of the query string itself, in the variables section, and passed to the arguments.
When we start working with variables, we need to do three things:
- Replace the static value in the query with $variableName
- Declare $variableName as one of the variables accepted by the query
- Pass variableName: value in the separate, transport-specific (usually JSON) variables dictionary
query($locationUuid: String, $tabCreationDate: Datetime) {
locations: locationsList(condition: { locationUuid: $locationUuid }) {
tabs: tabsList(
filter: {
created: { greaterThan: $tabCreationDate }
ordersPlaced: { greaterThan: 0 }
}
) {
name
tabMode
tax
total
subtotal
tippedSubtotal
balanceDue
autogratDue
href
items: itemsList(filter: { ordered: { equalTo: true } }) {
name
created
unitPrice
unitPriceInitial
quantity
quantityInitial
subtotal
subtotalInitial
comped
voided
fee
discount
adjustments: adjustments {
adjustmentReason
adjustmentType
quantity
unitPrice
deltaTax
deltaAutograt
deltaAutogratTax
}
}
}
}
}
curl -L -X POST 'https://gotab.io/api/v2/graph' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoicG9zdGdyYXBoaWxlX3RydXN0ZWQiLCJ1c2VyX2lkIjoiMTYxNzciLCJpYXQiOjE2NDk5NTIyOTMsImV4cCI6MTY1MDAzODY5MywiYXVkIjoicG9zdGdyYXBoaWxlIiwiaXNzIjoicG9zdGdyYXBoaWxlIn0.6CoKGXHEv76ibJY5M6ihDRJGjjhwnwP39k_rOqt73AU' \
-H 'Content-Type: application/json' \
-H 'Cookie: heroku-session-affinity=AECDaANoA24IAWEJWvX///8HYgAOh+ViAA7mtWEEbAAAAANtAAAABXdlYi4ybQAAAAV3ZWIuM20AAAAFd2ViLjFqJjR8ha4Y+4UCK4kZ5AEvMSsJk7w_' \
--data-raw '{"query":"query($locationUuid: String, $tabCreationDate: Datetime) {\n locations: locationsList(condition: { locationUuid: $locationUuid }) {\n tabs: tabsList(\n filter: {\n created: { greaterThan: $tabCreationDate }\n ordersPlaced: { greaterThan: 0 }\n }\n ) {\n name\n tabMode\n tax\n total\n subtotal\n tippedSubtotal\n balanceDue\n autogratDue\n \n href\n\n items: itemsList(filter: { ordered: { equalTo: true } }) {\n name\n created\n\n unitPrice\n unitPriceInitial\n\n quantity\n quantityInitial\n\n subtotal\n subtotalInitial\n\n comped\n voided\n\n fee\n discount\n\n \n adjustments: adjustments {\n adjustmentReason\n adjustmentType\n\n quantity\n unitPrice\n deltaTax\n deltaAutograt\n deltaAutogratTax\n }\n }\n }\n }\n}","variables":{"Datetime":"04152022","locationUuid":"xyz"}}'
GraphQL IDE
One of the most powerful parts of GraphQL is its visual interface. The Apollo Studio Explorer is a powerful web IDE for creating, running, and managing GraphQL operations
Before diving in and querying the API, it’s highly recommended for you to run your queries through this visual interface. This will allow you to ensure that your queries are correct, and the data being returned is expected.
GoTab's GraphQL Explorer is available on Apollo Studio.