> For the complete documentation index, see [llms.txt](https://docs.heisenware.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.heisenware.com/~/changes/Q625pQNc0nXqVGPtyjAY/building-apps/integration/protocol-connectors/graphql-wip.md).

# GraphQL (WIP)

GraphQL is a query language for APIs that provides a more efficient, powerful, and flexible alternative to REST. It allows clients to request only the data they need, and nothing more, streamlining interactions between the client and server.

#### Differences between REST and GraphQL

* **Data Fetching**:
  * **REST**: Multiple endpoints are needed to fetch different types of data.
  * **GraphQL**: A single endpoint can be used to fetch all required data, reducing the number of server requests.
* **Data Structure**:
  * **REST**: Returns fixed data structures defined by the server.
  * **GraphQL**: Allows clients to specify the exact structure and fields they need.
* **Overfetching/Underfetching**:
  * **REST**: Often results in overfetching (fetching more data than needed) or underfetching (requiring multiple requests for complete data).
  * **GraphQL**: Clients only fetch the data they request, avoiding both overfetching and underfetching.
* **Versioning**:
  * **REST**: Typically requires versioned URLs or headers to manage changes in the API.
  * **GraphQL**: Avoids the need for versioning by allowing clients to request the exact data shape they need.
* **Community and Ecosystem**:
  * **REST**: More mature and widely used with a larger ecosystem.
  * **GraphQL**: Gaining popularity rapidly with a growing ecosystem.

## Do a GraphQL transaction

Using the `request` function, you can do a transaction on an existing GraphQL API.

There are multiple parameters at play for this request:

<table><thead><tr><th width="126">Parameter</th><th width="83">Type</th><th width="93">Default</th><th>Description</th></tr></thead><tbody><tr><td>url</td><td>String</td><td></td><td>The GraphQL API endpoint.</td></tr><tr><td>document</td><td>String</td><td></td><td>Your GraphQL request. Either a query or a mutation in GraphQL notation.</td></tr><tr><td>variables</td><td>Object</td><td></td><td>Optionally provide variables with this parameter.</td></tr><tr><td>headers</td><td>Object</td><td></td><td>Any header key-value pairs (e.g. for authorization).</td></tr></tbody></table>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.heisenware.com/~/changes/Q625pQNc0nXqVGPtyjAY/building-apps/integration/protocol-connectors/graphql-wip.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.