GraphQL Basics in IZI
Esta página aún no está disponible en tu idioma.
GraphQL Basics in IZI
Section titled “GraphQL Basics in IZI”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.
Anatomy of a Request
Section titled “Anatomy of a Request”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 codeInvalidInput$clubId: ID!— a required (!) variable of type IDclub(id: $clubId)— field call with an argument- Nested fields — select only what you need
Three Operation Types
Section titled “Three Operation Types”query — reading data
Section titled “query — reading data”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 — changing data
Section titled “mutation — changing data”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 — real-time events
Section titled “subscription — real-time events”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>" }.
Variables
Section titled “Variables”Never interpolate data directly into the query string — it’s both a security risk and inconvenient:
# ❌ Bad — string interpolationquery GetClubName { club(id: "8b0f8c3e-...") { name }}
# ✅ Good — variablesquery GetClubName($id: ID!) { club(id: $id) { name }}# Variables: { "id": "8b0f8c3e-..." }Fragments
Section titled “Fragments”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 } }}Error Handling
Section titled “Error Handling”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.
Schema
Section titled “Schema”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.
Request Limits
Section titled “Request Limits”- 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
limitorfirst. A more complex query is rejected before execution with the codeQUERY_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.
Recommended Clients
Section titled “Recommended Clients”| Client | Use Case |
|---|---|
| Insomnia | Development and debugging |
| Apollo Client | Frontend (React/Vue) |
graphql-request | Node.js scripts and backend |
gql + httpx | Python |
Related Pages
Section titled “Related Pages”- IZI API: Overview — per-contour addresses and access
- Authentication & Tokens — how to get a token
- API Error Codes — what errors mean
- SDK Examples — ready wrappers for JS/Python
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.
IZI LLC (ООО «ИЗИ»), TIN 7842227686, OGRN 1257800012249, office 1, premises 3-N, lit. A, 15-17 Perekupnoy lane, Saint Petersburg, 191024, Russia, admin@izi.is · Cookie settings