# Getting Started

## Usage

The GraphQL API can be queried either through a GUI interface or programmatically.

### Graph*i*QL (GUI)

The Graphical User Interface maintained at <https://api.defikingdoms.com/graphql> is a great way to get started using the API and learning its syntax, as well as for quick lookups.

![GraphiQL interface for the community API](/files/ZPkloJwCu8zK15h34ZPN)

The `Docs` section in the top right-hand corner contains the full schema for the API, and the code editor will auto-complete.

### Javascript

Basic query implementation using the [`graphql-request`](https://github.com/prisma-labs/graphql-request) library.

```javascript
import { GraphQLClient, gql } from 'graphql-request'

const url = 'https://api.defikingdoms.com/graphql'
const query = gql`
  query getHero($heroId: ID!){
    hero(id: $heroId) {
      id
      mainClass
      owner {
        id
        name
      }
    }
  }`
const variables = {heroId: 1}

const client = new GraphQLClient(url)
client.request(query, variables).then((data) => console.log(data))
```

### Python

Basic query implementation using the [`requests`](https://pypi.org/project/requests/) library.

```python
import requests

url = 'https://api.defikingdoms.com/graphql'
query = """
  query getHero($heroId: ID!){
    hero(id: $heroId) {
      id
      mainClass
      owner {
        id
        name
      }
    }
  }
"""
variables = {'heroId': 1}

result = requests.post(url, json={'query': query, 'variables': variables})
print(result.json())
```

## Syntax

### Basic Query Syntax

```graphql
{
  queryField(arg1: argument, arg2: argument) {
    subfield1
    subfield2
    subfield3 {
      sub-subfield1
      sub-subfield2
    }
  }
}
```

Example query on the `hero` object:

```graphql
{
  hero(id: 1) {
    id
    mainClass
    owner {
      id
      name
    }
  }
}
```

{% hint style="info" %}
Because subfields may be an *object* type themselves (e.g. `Hero`, `Profile`), you can access the object's own fields without multiple queries or cumbersome joins, as in the example above, where `owner` is a `Profile` object.
{% endhint %}

{% hint style="warning" %}
Note that the GraphQL server has a recursion limit on accessing object type subfields, in most cases limited to 3 levels of depth.
{% endhint %}

### Arguments

All top-level query fields take arguments, set by the particular field. Every operation has two varieties: one that returns a single result and one that returns multiple results (e.g. `hero`/`heroes`, `saleAuction`/`saleAuctions`).

{% hint style="info" %}
*Only* top-level query fields can take arguments.
{% endhint %}

#### **Single-Result** Queries

These fields only take a single argument:

* `id`: `Int`/`String` - the id of the `Hero`, `Auction`, `Pet`, or `Profile`.

#### **Multiple-Result Queries**

These fields take any of the following *optional* arguments:

* `first`: `Int` - the number of requested results. Default: `1000`; Max: `1000`.
* `skip`: `Int` - skip the first *x* results. Default: `0`. Use to iterate beyond the 1000 result maximum per query.
* `orderBy`: `Subfield` - the subfield to order results by. Default: `id`.
* `orderDirection`: `asc`/`desc` - the order direction of the results. Default: `asc`.
* `where`: {`ObjectArray`} - Adds a [Filter](#filters) to the results.

*Example:* a `heroes` query using default arguments

```graphql
{
  heroes(first: 1000, skip: 0, orderBy: id, orderDirection: asc) {
    id
  }
}
```

### Filters

The optional `where` argument on a multi-result query allows for a high degree of flexibility. Any number of field/value pairs can be added to the array, with optional operators using the following syntax: `field_operator: value`.

{% hint style="info" %}
A filter used on an object field (e.g. `Hero`, `Auction`, `Pet`) will filter on that object's `id`, and cannot be used to access any of its other subfields.
{% endhint %}

#### **Operators**

* \[`none`] - equal to
* `_not` - not equal to
* `_gt` - greater than
* `_gte` - greater than or equal to
* `_lt` - less than
* `_lte` - less than or equal to
* `_in` - found in `[List]`
* `_not_in` - not found in `[List]`

*Example:* the Top 5 Ninja/Thief Heroes with the Fishing gene (ordered descending by Fishing skill)

```graphql
{
  heroes(
    first: 5, 
    orderBy: fishing, 
    orderDirection: desc, 
    where: {
      profession: "fishing", 
      mainClassStr_in: ["Ninja", "Thief"]
    })
  {
    id
    fishing
  }
}
```

### Variables

To add a variable to a query, three things are required:

1. Replace the static value in the query with `$variableName`
2. Declare `$variableName` as one of the variables accepted by the query and assign it a type (e.g. `ID`, `Int`, `String`, `Boolean`)
3. Pass `variableName: value` in a separate variables dictionary

```graphql
# Query with declared variable
query getHero($heroId: ID!) {
  hero(id: $heroId) {
    id
    mainClass
  }
}

# Variable passed as dictionary
{
  "heroId": 1
}
```

The example above also includes an expanded syntax beginning with the `query` *operation type*, and a user-declared *operation name* (`getHero`) for the function. The operation type is required to use variables, while the operation name is optional.

### Aliases and Fragments

#### Aliases

Using an *alias* allows you to include the same field type in your query multiple times with different arguments.&#x20;

*Example:* a single query that separately returns Pets hatched from Blue and Grey Eggs, respectively.

```graphql
{
  blueEggs: pets(where: {eggType: 0}) {
    id
  }
  greyEggs: pets(where: {eggType: 1}) {
    id
  }
}
```

#### Fragments

*Fragments* allow you to reuse the same subfields on multiple operations in a single query, without having to re-type them for each instance.

*Example:* expanding on the previous query to request a range of fields for each operation.

```graphql
query {
  blueEggs: pets(where: {eggType: 0}) {
    ...petInfo
  }
  greyEggs: pets(where: {eggType: 1}) {
    ...petInfo
  }
}

fragment petInfo on Pet {
  id
  rarity
  appearance
  owner {
    name
  }
}
```

{% hint style="info" %}
For more on Aliases, Fragments, and other advanced syntax like Mutations and Directives, see the [GraphQL Documentation](https://graphql.org/learn/).
{% endhint %}


---

# Agent Instructions: 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://devs.defikingdoms.com/api/community-graphql-api/getting-started.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.