# Learn GraphQL

Source: https://swapcard.dev/guides/graphql-learning


Swapcard's Content and Leads APIs are GraphQL APIs. Here is what you need to know to use them well.

## Why GraphQL

- **Ask for exactly what you need.** A request lists the fields it wants, and the response has the same shape, with nothing more.
- **One endpoint.** Every operation goes to the same URL; what changes is the query you send.
- **A typed, self-describing schema.** Every field has a type, invalid input is rejected before anything runs, and tools like the [API Explorer](/content-api/discover-explorer) can autocomplete the whole API.
- **Works with any language.** GraphQL is plain JSON over HTTP, and [client libraries](https://graphql.org/code/) exist for every major stack.

## Why GraphQL works well with AI coding tools

If you build with an AI assistant (Claude Code, Cursor, Copilot or your own agent), GraphQL gives it more to work with than a typical REST API:

- **The schema is a machine-readable contract.** Through introspection, an assistant can discover every type, field and argument at runtime instead of guessing endpoints and parameter shapes from prose.
- **Mistakes are caught before anything runs.** If a model invents a field or passes the wrong type, the server rejects the operation with a precise validation error, which the assistant can read and fix on its own.
- **Smaller responses, less context.** Asking only for the fields you need keeps responses short, so more of the model's context window stays available for your code.

This works best when the schema is descriptive: clear names and field descriptions are what the model actually reads. Much of the writing on this comes from GraphQL tooling vendors, so treat it as practical guidance rather than measured benchmarks. See [GraphQL: Supercharging AI](https://graphql.org/blog/2025-07-03-graphql-supercharging-ai/) on graphql.org for a broader take.

**Tips for using Swapcard's APIs with an assistant:**

1. Give it the docs: use **Copy for LLM** on any page, or point it at [`/llms.txt`](pathname:///llms.txt) for an index of every guide in Markdown.
2. Let it check its work: paste generated operations into the [API Explorer](/content-api/discover-explorer), which validates them against the live schema.
3. Keep operations in `.graphql` files and generate types from the schema, so mistakes surface at build time rather than in production.

## Core concepts

### Queries and mutations

A **query** reads data, and a **mutation** changes it. Both are sent as a `POST` with a JSON body containing the operation and its variables:

```json
{
  "query": "query EventById($eventId: ID!) { event(id: $eventId) { title } }",
  "variables": { "eventId": "<EVENT_ID>" }
}
```

### Variables

Keep operations static and pass values through `variables`, as above. This avoids string-building bugs and makes operations reusable.

### Pagination

List fields are paginated. Request a page with `pageSize` (maximum **200**; **100** is recommended), or use cursors: query with `first`, then pass the returned `endCursor` as `after` to get the next page.

### Errors

A GraphQL response can return HTTP `200` and still contain an `errors` array. Always check `errors` as well as the HTTP status. Many mutations also return their own `errors` field with validation messages.

## Further reading

- [Learn GraphQL](https://graphql.org/learn/) and [best practices](https://graphql.org/learn/best-practices/) on graphql.org
- [Serving over HTTP](https://graphql.org/learn/serving-over-http/) and [execution](https://graphql.org/learn/execution/)
- [GraphQL clients](https://graphql.org/graphql-js/graphql-clients/)
- [Forming calls with GraphQL](https://docs.github.com/en/graphql/guides/forming-calls-with-graphql) (GitHub's guide applies to any GraphQL API)