Getting started with the API: Permissions, Filters and Pagination

  • Updated

 

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

 

Related articles