Skip to content
Tutorials Center
My learning

Topics

Lesson 8 of 28 ยท GraphQL

GraphQL Admin API and Choosing Between APIs

Learn the BigCommerce GraphQL Admin API, how to explore it in GraphiQL, how query complexity limits work and how to choose between REST and GraphQL.

BigCommerce offers more than one way to read and change store data, and a good developer picks the right one for each job instead of using a single style everywhere. You already know the REST APIs and the Storefront GraphQL API. This lesson adds the third: the GraphQL Admin API, which uses your server-side credentials like REST does, but lets you shape the response like GraphQL does.

You will learn how the Admin API is reached, how to explore it, why every query has a cost, and how to decide between REST and GraphQL. The platform calls are read-only snippets. The runnable stand-ins are Node.js programs: one measures the cost of a query tree and enforces a budget, the other encodes a decision guide. The numbers in them are invented for teaching, because the real limits belong to the platform and may change; always read the current documentation before you rely on a figure.

The Admin API in one picture

The Admin GraphQL API is served from the same API host as REST, under your store's path, and you authenticate with the same X-Auth-Token header and scopes you set up in API Accounts, Tokens and Scopes. The request is a POST with a JSON body (read-only):

HTTP
POST /stores/{store_hash}/graphql HTTP/1.1
Host: api.bigcommerce.com
X-Auth-Token: <access token>
Content-Type: application/json

{"query": "query { store { ... } }"}

Do not confuse the two GraphQL APIs. The Storefront API runs on a storefront domain, uses a public-safe bearer token and serves shopper-facing data. The Admin API runs on the API host, uses a private token and serves management data. The Admin schema does not cover everything REST does, and it grows over time, so treat the schema browser as the source of truth for what exists today.

flowchart TD
    subgraph server["Your server"]
      A["Admin token"]
    end
    subgraph browser["Browser or headless app"]
      T["Storefront token"]
    end
    A --> R["REST<br/>api.bigcommerce.com/.../v3"]
    A --> G1["Admin GraphQL<br/>api.bigcommerce.com/.../graphql"]
    T --> G2["Storefront GraphQL<br/>shop domain/graphql"]

Admin credentials reach REST and Admin GraphQL; the storefront token reaches only Storefront GraphQL.

Exploring with GraphiQL

GraphQL APIs describe themselves. The schema lists every type, field and argument, and you can ask for it with an introspection query. Tools such as GraphiQL turn that into an editor with autocomplete and inline documentation. BigCommerce provides a GraphQL playground for the APIs (the developer documentation links to it, and the control panel offers one for storefront queries). The workflow is simple:

  1. Open the playground and supply your token.
  2. Read the documentation panel to find the type you need.
  3. Build the query field by field, letting autocomplete show valid names.
  4. Run it, then copy the final query into your code and replace literal values with variables.

Exploration is cheap and safe for read queries. For mutations, use a sandbox store, as described in Setting Up a Development Environment.

Query cost and limits

Every GraphQL API has to protect itself from queries that ask for too much. A single innocent-looking request can fan out: 250 products, each with 250 variants, each with options, is a very large amount of work. BigCommerce therefore assigns each query a complexity (cost) and enforces limits, in two ways:

  • A maximum cost per query. If a query is too expensive it is rejected up front, and you must request less or split it.
  • A rate limit based on cost, not only on the number of requests. Many cheap queries and a few expensive ones can use the same budget.

Cost is driven mainly by list sizes. A connection with first: 50 costs roughly 50 times what a single object costs, and nested connections multiply. This is why the advice from the storefront lesson holds here too: ask for the fields you need and no more, and keep first as small as the use case allows.

The platform reports limit problems in its responses (check the current documentation for the exact fields); log them in your client. Handling the "slow down" signal with backoff is the same pattern you will practice in Orders, Customers and the V2/V3 Split.

Batching with aliases and variables

A GraphQL request can contain several top-level fields. With aliases you can fetch two different slices in one round trip, such as the newest ten products and the featured ten, under two names. That cuts latency, but it does not make the work free: the cost of the combined query is the sum of its parts, so a batch can exceed the per-query maximum even if each part alone would not. Batch to save round trips, and watch the total.

Also remember the difference between batching reads and batching writes. For bulk writes, REST V3 endpoints often accept arrays of objects, which is the usual route for large catalog updates (see The Catalog API (V3)).

A cost-limiter stand-in

The program below models a query as a tree. Each field costs 1. A connection field has first, and the cost of its children is multiplied by first. A query above a maximum is rejected, and a budget per time window is drained by the cost of the queries that run. All numbers are invented for the demo; only the idea (cost grows with list size, with nesting multiplying) matches the real design.

Node.js Measure query cost and enforce a budget

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The heavy query is rejected before it runs, because nested lists multiply: 50 products times 50 variants is expensive. Trimming the page sizes brings it under the maximum. After a few more runs the window budget is spent and the limiter throttles the rest. In a real client, a throttled response is your cue to wait, not to hammer the endpoint.

Choosing between REST and GraphQL

There is no winner in general, only a better fit per task. Use these questions:

  • Who is asking? Shopper-facing code in a browser or a headless app uses the Storefront GraphQL API. Server code managing the store uses REST or Admin GraphQL.
  • Does the operation exist there? Some operations are only in REST (many bulk and legacy V2 endpoints), some only in GraphQL. Check before you design around one.
  • Do you read many shapes or one fixed shape? GraphQL shines when different screens need different fields. REST is fine, and often simpler, when you always want the whole resource.
  • Is it a bulk write? Prefer REST array endpoints designed for it.
  • Does the team know it? A familiar API with good tooling beats a clever choice nobody can debug.

The second stand-in turns those questions into a function. It is intentionally simple, but writing your rules down like this is a good way to keep a team consistent.

Node.js A small API decision guide

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The decision for "legacy order status update" depends on a fact you must verify in the current documentation, which is why the guide takes it as an input instead of hard-coding it. Real choices should be reviewed whenever the platform adds schema coverage.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which credential does the Admin GraphQL API use?

    The Admin API is a management surface. It uses your server-side token in X-Auth-Token and the account scopes.
  2. 2. Why can a query with first 50 products and first 50 variants be rejected?

    Cost grows with list sizes and nesting multiplies it. Reduce page sizes or split the query.
  3. 3. What does batching several fields with aliases NOT do?

    The combined query costs about the sum of its parts. Batching saves latency, not budget.
  4. 4. For importing thousands of products, which is usually the better fit?

    Bulk-write endpoints are built for this job and keep request counts low.
  5. 5. What is the best use of a GraphiQL playground?

    Playgrounds make the schema discoverable. Copy the finished query into your app and use variables.

Summary

  • Admin GraphQL runs on the API host with your private token and scopes; Storefront GraphQL runs on the shop domain with a limited token.
  • Explore the schema with GraphiQL and introspection, then move queries into code with variables.
  • Queries have a cost; nested lists multiply it, and both per-query and rate limits apply.
  • Aliases batch reads to save round trips but not budget; bulk writes belong to REST array endpoints.
  • Choose the API by who calls, what exists, how shapes vary and what your team can maintain.

Next: App Types and the OAuth Flow