Root schemas & permissions
Now that you’re authenticated, we can take a look at the different root schemas and their respective permissions. We start off with two trees within our graph: query and mutation. Query will be your best friend to fetch data, while mutation is the transactional handler of all creations and updates.
Query
The data that can be fetched from the server is divided into five sections, each with their own permissions:
Distribution
The public resources that are necessary to visualize your web shop’s content; like events, ticket types, event groups, seat categories,… are contained within the distribution (which is a synonym for web shop) schema. A distributionId is required for the API to know what distribution to look for.
The following example shows a query that fetches all events, their title and their prices with fee and translation data of distribution with id 123:
query distribution { distribution(id:123) { events { title ticketTypes { translation(langCode:EN) priceDetail { base exclFee } } } } }
In theory everyone can request this public info. All you need is any access token.
Purchase
Upon creating a purchase using the public distribution mutation, the access token is signed with the purchaseId. From that point forward, this access token can request purchase related information such as price, customer data, ticket data and payments.
Only one purchase can be assigned to one public access token at a given time.
The following example fetches purchase data for the purchase that is assigned to the current access token:
query purchase { purchase { id price tickets { id price barcode } payments { ...on PublicSupervisedPayment { id confirmedAt price } ...on PublicWireTransferPayment { id confirmedAt price } } } }
Customer
Identical to the purchase resource, the customer resource can show customer (& purchase) related information as soon as the access token is signed with the customerId, by logging in.
It’s worth mentioning that the aforementioned purchase can now optionally be provided with a purchaseId. All purchases that are related to the customerId of the access token can be fetched. Easier is using the purchases function on the customer resource.
query customer { customer { firstName lastName email addresses { id city postalCode } } } query purchase { purchase(id:123) { id price tickets { id price barcode } payments { ...on PublicSupervisedPayment { id confirmedAt price } ...on PublicWireTransferPayment { id confirmedAt price wireTransferInformation { bic bankDetails } } } } }
Operator
An access token that has been created using an operator e-mail and password has access to all the operator related resources.
Most operator related resources exist twice. Let’s take the event resource as an example:
- operator.events
- operator.configurableEvents
The difference in these functions are the permissions.
- The operator.events function returns all events for which the logged in operator can sell a ticket.
- The operator.configurableEvents function returns all events for which the logged in operator can make configuration changes.
You’ll want to use the configurable functions for event configuration applications (e.g. back-office), and the regular ones for sale application (e.g. box-office/POS).
Sale functions
An operator that is configured to 1 or more distributions (=sale channels), can perform sales inside these distributions. The operator has access to a big scala of resources that are necessary to perform the actual sale.
Some examples are:
query sales { operator { events { ticketTypes { translation(langCode:EN) } } distributions { title } eventGroups { title } customers { email } } }
Configuration functions
An operator that is configured to 1 or more organizers, can perform configuration for these organizers and their events.
Some examples are:
query config { operator { configurableEvents { ticketTypes { translation(langCode:EN) } } configurableDistributions { title } configurableEventGroups { title } configurableEventsCount } }
Most organizations will have more sale operators than configuration operators.
Admin
An admin is a special kind of operator that has admin permissions. He has access to all resources within his platform using the operator schema. Additionally he can fetch extra data using the admin schema.
Example:
query admin { admin { organizations { id title } organizers { id title team { id email } } } }
Within the admin schema, the focus is on the platform organizers and organizations. For more information about this setup checkout our organizational blogpost.
Mutation
Inside the mutation schema, we bundle all CRUD actions. The underlying divisions are very similar to the different levels inside query:
- Public: all mutations for access tokens that are signed with a purchaseId (client-to-server)
- Operator: all operator mutations
- Admin: all admin mutations
Filters & pagination
An important feature in the API, is the use of filter & pagination parameters when fetching lists or counts. These parameters will help you to request the data in a performant way. All list functions have (most of) the following parameters (if applicable):
- Where: The filter that is used for the list or count
- Limit: The amount of results returned by the API. This is set to 10 by default and should not be higher than 500 to ensure satisfiable performance
- Offset: The offset is used in combination with aforementioned limit to create some sort of pagination. Combined you can use both to loop through all results
- Order: The sorting that should be used for the list
The following example shows how to fetch all issued tickets of an event in batches of 500:
query fetchTickets { operator { events { tickets (where:{status: [CONFIRMED, RELEASED], issued:true, updatedAfter: "2017-10-05T22:50:05.000Z"}, limit: 500, offset:1500, order: {order: DESC, sort: "id"}){ id status barcode scanState createdAt updatedAt } } } }
Continue reading about errors and handling them