Getting Started

Usage

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

GraphiQL (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

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 library.

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 library.

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

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

Example query on the hero object:

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

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.

Note that the GraphQL server has a recursion limit on accessing object type subfields, in most cases limited to 3 levels of depth.

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).

Only top-level query fields can take arguments.

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 to the results.

Example: a heroes query using default arguments

{
  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.

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.

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)

{
  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

# 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.

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

{
  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.

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

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

For more on Aliases, Fragments, and other advanced syntax like Mutations and Directives, see the GraphQL Documentation.