Comment on page
Getting Started
The GraphQL API can be queried either through a GUI interface or programmatically.
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.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))
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())
{
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.
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.
These fields only take a single argument:
id
:Int
/String
- the id of theHero
,Auction
,Pet
, orProfile
.
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
.
Example: a
heroes
query using default arguments{
heroes(first: 1000, skip: 0, orderBy: id, orderDirection: asc) {
id
}
}
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.- [
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
}
}
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.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 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.
Last modified 1mo ago