> ## Documentation Index
> Fetch the complete documentation index at: https://dev.ownright.com/llms.txt
> Use this file to discover all available pages before exploring further.

# GraphQL

> The underlying technology that powers our platform

The Ownright Developer Platform is built using [GraphQL](https://graphql.org/), a modern query language for APIs that
gives you precise control over the data you request. While GraphQL may be less familiar
than traditional REST APIs, it unlocks a more flexible and efficient way to interact with
our platform.

## 🧠 What is GraphQL?

GraphQL is a query language and runtime for APIs originally developed by Facebook.
Unlike REST, which requires multiple endpoints for different data needs, GraphQL exposes
a single endpoint that allows clients to:

<ul>
  <li>Ask for exactly the data they need, and nothing more</li>
  <li>Retrieve nested, related data in a single request</li>

  <li>
    Use a strongly-typed schema to understand what's possible to query or mutate
  </li>
</ul>

All requests to our APIs are made as POST requests to a GraphQL endpoint.
Queries and mutations are written in the GraphQL syntax, and responses are returned in
predictable JSON format.

## 🚀 Why we chose GraphQL

We chose GraphQL because our integrators range from fast-moving startups to established platforms — all with different integration needs.

GraphQL gives your team:

<ul>
  <li>**Flexibility**: Fetch exactly the data you need—no more, no less.</li>

  <li>
    **Efficiency**: Minimize payload size and reduce over-fetching to improve
    performance.
  </li>

  <li>
    **Discoverability**: Explore the schema with introspection, enabling faster
    onboarding.
  </li>

  <li>
    **Scalability**: Confidently build on top of an API that evolves without
    breaking your integration.
  </li>
</ul>

Put simply: GraphQL helps you build faster, cleaner integrations that grow with your product.

## 🛠 GraphQL in action

Here's an example of a simple GraphQL query:

```graphql GraphQL query example theme={null}
query GetReferral {
  referral(id: "gid://ownright/Referral/1") {
    id
    kind
    status
    ...
    # other fields
    ...
    createdAt
    updatedAt
  }
}
```

And here's an example mutation:

```graphql GraphQL mutation example theme={null}
mutation CreatePurchaseReferral {
  purchaseReferralCreate(
    input: {
      address: {
        street: "123 Main St"
        city: "Toronto"
        # ... other input
      }
      # ... other input
    }
  ) {
    referral {
      id
      status
    }
  }
}
```

Each API has its own endpoint — refer to the **Connecting** page in your API's reference section for the specific URL.

## 📚 Learn more about GraphQL

If you're new to GraphQL or want to brush up your skills, here are some great resources:

<ul>
  <li>
    [graphql.org/learn](https://graphql.org/learn) – The official GraphQL
    introduction
  </li>

  <li>
    [How to GraphQL](https://www.howtographql.com/) – A free fullstack GraphQL
    tutorial
  </li>

  <li>
    [Apollo GraphQL Docs](https://www.apollographql.com/docs/) – For tooling,
    best practices, and client-side usage
  </li>

  <li>
    [Postman GraphQL
    Guide](https://learning.postman.com/docs/sending-requests/graphql/graphql-overview/)
    – GraphQL in familiar tools
  </li>
</ul>

## 💡 Developer tip

Many GraphQL clients (like [Insomnia](https://insomnia.rest/), [Postman](https://www.postman.com/), or [GraphiQL](https://github.com/graphql/graphiql))
offer built-in schema explorers. This lets you view available queries, mutations, and types without leaving your
dev environment.