Ir al contenido

GraphQL Basics in IZI

Опубликовано: · Обновлено: (сегодня)· IZI Team

Esta página aún no está disponible en tu idioma.

GraphQL is a query language where you describe exactly what data you want. Unlike REST, there are no multiple endpoints: one address, one POST, and you choose the fields.

If you’ve worked with REST before, the key shift: stop thinking of URLs as resources. Here the URL is always /graphql on the API host of your contour, for example https://api.x.izi.is/graphql (all contour addresses). What to do is described in the request body.

query GetClub($clubId: ID!) {
club(id: $clubId) {
id
name
timezone
city
address
}
}

Breaking it down:

  • query — operation type (read data)
  • GetClub — operation name. Required: the server rejects an operation without a name with the code InvalidInput
  • $clubId: ID! — a required (!) variable of type ID
  • club(id: $clubId) — field call with an argument
  • Nested fields — select only what you need
query StartedSessions($clubId: ID!) {
sessions(filters: { clubId: $clubId, statuses: [STARTED] }) {
items {
id
status
actualStartAt
plannedEndAt
}
totalCount
}
}

Variables are passed as a separate object:

{
"clubId": "8b0f8c3e-..."
}

The sessions query requires a club employee token (CRM) or a player token (PLAYER).

mutation NarrowTokenToClub($clubId: ID!) {
exchangeClubToken(clubId: $clubId) {
accessToken
}
}
{
"clubId": "8b0f8c3e-..."
}

A mutation returns the result of the operation. If it fails, the response contains errors — don’t rely on HTTP 200 alone.

subscription ClubSessionUpdates($clubId: ID!) {
sessionUpdates(clubId: $clubId) {
id
status
plannedEndAt
}
}

Subscriptions run over WebSocket using the graphql-ws protocol on the same address: wss://api.x.izi.is/graphql for the main contour. The token is passed not in a header but in connectionParams when connecting: { "Authorization": "Bearer <token>" }.

Never interpolate data directly into the query string — it’s both a security risk and inconvenient:

# ❌ Bad — string interpolation
query GetClubName {
club(id: "8b0f8c3e-...") {
name
}
}
# ✅ Good — variables
query GetClubName($id: ID!) {
club(id: $id) {
name
}
}
# Variables: { "id": "8b0f8c3e-..." }

If the same fields are needed across multiple queries, extract them into fragments:

fragment ClubCard on Club {
id
name
city
address
}
query ClubsInCity($search: String!) {
clubs(filters: { search: $search }) {
items {
...ClubCard
}
}
}

An IZI API response always contains data and optionally errors:

{
"data": null,
"errors": [
{
"message": "Permission denied",
"path": ["exchangeClubToken"],
"extensions": {
"code": "Forbidden",
"message": "Permission denied"
}
}
]
}

HTTP status can still be 200. Always handle the errors field explicitly — don’t rely on HTTP codes for business errors. Error format and common codes: API Error Codes.

Introspection is disabled on every contour: __schema and __type queries return an error, and GraphQL clients cannot load the schema on their own. To get the current schema (SDL), contact IZI.

  • One operation per POST: batched requests (an array of operations) are disabled — the answer is HTTP 400 with the code BAD_REQUEST.
  • Field nesting depth — at most 9 levels. The limiter is set to 8 and counts the root field as level zero, so nine levels pass and the tenth is rejected: HTTP 400, code GRAPHQL_VALIDATION_FAILED, message 'OperationName' exceeds maximum operation depth of 8.
  • Query complexity — at most 750, where each requested field costs 1 and there are no multipliers for limit or first. A more complex query is rejected before execution with the code QUERY_TOO_COMPLEX — but it arrives with HTTP status 500, so do not read that answer as a server fault and do not retry it.
  • Request body — at most 256 KB; exceeding it gives HTTP 413 with the code PAYLOAD_TOO_LARGE.

Those are limits on the shape of a request. Separately from them, some operations carry rate budgets, and they are counted neither per token nor per IP as a whole, but on each operation’s own key: password sign-in by email and IP pair, public player registration by IP and by club, device pairing-code exchange by IP, top-ups and code sending by player. Exceeding one answers TooManyAttempts (some operations use their own code), and the API deliberately does not disclose how long the block lasts: there is no Retry-After header and no retryAfter field in the response. There is no global “N requests per second per token” limit on /graphql — the API never returns a 429 at all.

ClientUse Case
InsomniaDevelopment and debugging
Apollo ClientFrontend (React/Vue)
graphql-requestNode.js scripts and backend
gql + httpxPython

Preguntas frecuentes

What is the difference between query and mutation in IZI API?

A query reads data without changing state. A mutation changes data: starts a session, updates club settings, issues a token. The rule is simple: if the operation changes something, it's a mutation.

Can I send multiple queries in one POST?

No. Batched requests (an array of operations in the body) are disabled: one POST, one operation.

How do I discover all available fields and types?

Introspection is disabled on IZI contours; __schema and __type queries return an error. Request the current schema (SDL) from IZI.

What is the N+1 problem and how does IZI handle it?

N+1 is when fetching a list of N objects triggers N additional queries. IZI API uses DataLoader: related objects are batch-loaded automatically.

About IZI