From 1c0fbd52332ee5632f2a2f210ca27b98b56eb51c Mon Sep 17 00:00:00 2001 From: Kyrch Date: Sat, 26 Jul 2025 17:35:49 -0300 Subject: [PATCH] docs(graphql): added nodes field explanation (#114) (cherry picked from commit 316aabdb2a4c617209e049aca07182819724cc61) --- .../examples/filter-by-external-site/index.md | 55 +++++++++++++++++++ docs/guide/examples/search/index.md | 2 + docs/guide/graphql/filtering/index.md | 18 +++--- docs/guide/graphql/pagination/index.md | 4 +- docs/guide/graphql/relationships/index.md | 40 +++++++++++--- .../graphql/{ordering => sorting}/index.md | 4 +- 6 files changed, 102 insertions(+), 21 deletions(-) create mode 100644 docs/guide/examples/filter-by-external-site/index.md rename docs/guide/graphql/{ordering => sorting}/index.md (66%) diff --git a/docs/guide/examples/filter-by-external-site/index.md b/docs/guide/examples/filter-by-external-site/index.md new file mode 100644 index 0000000..8f10902 --- /dev/null +++ b/docs/guide/examples/filter-by-external-site/index.md @@ -0,0 +1,55 @@ +--- +title: Filter by External Site +--- + +# Filter by External Site + +--- + +The AnimeThemes API provides an exclusive query for one of its most common use cases. +The `findAnimesByExternalSite` query accepts three arguments to filter animes by external resources. +An external resource may be linked to multiple animes. + +## Query Example + +```graphql +query ($id: Int!) { + { + findAnimesByExternalSite(site: ANILIST, id: $id) { + name + mediaFormat + season + year + } + } +} +``` + +## Authentication + +None + +## Parameters + +| Name | Type | Description | +| :---: | :-----------: | :---------------------------------------------------------------- | +| site | ResourceSite! | The site enum used to filter | +| id | Int | The id of the anime in the external site | +| link | String | The URL of the external resource. Required if no `id` provided. | + +## Response + +```json +{ + "data": { + "findAnimesByExternalSite": [ + { + "name": "Hibike! Euphonium 3", + "mediaFormat": "TV", + "season": "SPRING", + "year": 2024 + } + ] + } +} +``` \ No newline at end of file diff --git a/docs/guide/examples/search/index.md b/docs/guide/examples/search/index.md index eb5f543..217641c 100644 --- a/docs/guide/examples/search/index.md +++ b/docs/guide/examples/search/index.md @@ -4,6 +4,8 @@ title: Global Search # Global Search Query +--- + The global search query returns a listing of resources that match a given search term. ## Query Example diff --git a/docs/guide/graphql/filtering/index.md b/docs/guide/graphql/filtering/index.md index dc3126e..c459227 100644 --- a/docs/guide/graphql/filtering/index.md +++ b/docs/guide/graphql/filtering/index.md @@ -12,12 +12,12 @@ Most queries provide filtering arguments using the AND operator. Filtering argum | Name | Fields | Example | Description | | :-----: | :--------------------------------------------: | :--------: | ------------------------------------- | -| Eq | String, Int, Float, Boolean, enums, DateTimeTz | name | Add an `equal` conditional to the query | -| Like | String | name_like | Add a `like` conditional to the query | -| In | Int, Float, enums | id_in | Add an `in` conditional to the query | -| Not in | Int, Float, enums | id_not_in | Add a `not in` conditional to the query | -| Greater | Int, Float, DateTimeTz | id_greater | Add a `gt` conditional to the query | -| Lesser | Int, Float, DateTimeTz | id_lesser | Add a `lt` conditional to the query | +| Eq | String, Int, Float, Boolean, enums, DateTimeTz | name | Add an `equal` conditim to the query | +| Like | String | name_like | Add a `like` condition to the query | +| In | Int, Float, enums | id_in | Add an `in` condition to the query | +| Not in | Int, Float, enums | id_not_in | Add a `not in` condition to the query | +| Greater | Int, Float, DateTimeTz | id_greater | Add a `greater than` condition to the query | +| Lesser | Int, Float, DateTimeTz | id_lesser | Add a `less than` condition to the query | Query example: @@ -33,9 +33,9 @@ query { ## Trashed Filter -The queries that return a type that implements soft-deletes have a `trashed` filter. +Queries that return a type implementing soft deletes have a `trashed` filter. -The argument is: `trashed: Trashed`, which allows to filter if trashed elements should be fetched. +The argument is `trashed: Trashed`, which allows filtering to determine if trashed elements should be fetched. `Trashed` is an enum with the following values: @@ -57,7 +57,7 @@ query { ## Nested Filtering -Filtering in relationships is applied **ONLY** on the relationship and it doesn't affect the previous root. +Filtering in relationships is applied **ONLY** to the relationship and does not affect the previous root. ```graphql query { diff --git a/docs/guide/graphql/pagination/index.md b/docs/guide/graphql/pagination/index.md index 2214b9a..45872b2 100644 --- a/docs/guide/graphql/pagination/index.md +++ b/docs/guide/graphql/pagination/index.md @@ -23,7 +23,7 @@ There are two arguments available for every query that uses pagination. The following query ```graphql query { - animes(first: 15, page: 1) { + animes(first: 2, page: 1) { paginatorInfo { count currentPage @@ -40,7 +40,7 @@ query { } } ``` -will return a JSON like: +will return the JSON: ```json { "data": { diff --git a/docs/guide/graphql/relationships/index.md b/docs/guide/graphql/relationships/index.md index c2b2b31..e77a634 100644 --- a/docs/guide/graphql/relationships/index.md +++ b/docs/guide/graphql/relationships/index.md @@ -6,13 +6,13 @@ title: Relationships --- -The AnimeThemes API implements relationships for most types, previously known as allowed included in the REST API. +The AnimeThemes API implements relationships for most types, previously known as "allowed includes" in the REST API. -The many-to-many, one-to-many and polymorphic one-to-many relationships apply pagination. +The many-to-many, one-to-many, and polymorphic one-to-many relationships apply pagination. ## Many-to-One (BelongsTo) -A many-to-one relationship has a object that references the foreign type. +A many-to-one relationship has an object that references the foreign type. ```graphql query { @@ -29,7 +29,7 @@ query { ## One-to-Many (HasMany) -An one-to-many relationship has a list of objects that reference the related type. +A one-to-many relationship has a list of objects that reference the related type. ```graphql query { @@ -48,9 +48,18 @@ query { ## Many-to-Many (BelongsToMany) -A many-to-many relationship has a `edges` list that contains edge objects. +Every many-to-many relationship applies connection pagination and has three top fields. +Read about it in the [graphql.org](https://graphql.org/learn/pagination/#pagination-and-edges) +and [relay.dev](https://relay.dev/graphql/connections.htm) documentations if you don't know what it is. -The edge object contains the pivot fields of the relationship and a `node` object that references the related type. +The `pageInfo` field provides pagination information. + +The `nodes` field returns a list of objects that reference the related type. +Use this field if you don't care about the pivot fields of the relationship. + +The `edges` field returns a list of `edge` objects. +The `edge` object always contains a `node` field that returns a singular object of the related type, +and the pivot fields of the relationship. Both fields `createdAt` and `updatedAt` are available for every many-to-many relationship. @@ -61,7 +70,13 @@ query { data { name resources { - edges { + pageInfo { # Pagination + total + } + nodes { # Without pivot fields + link + } + edges { # With pivot fields node { link } @@ -83,6 +98,15 @@ will return the JSON: { "name": ".hack//Liminality", "resources": { + "pageInfo": { + "total": 6 + }, + "nodes": [ + { + "link": "https://myanimelist.net/anime/299" + }, + ... + ], "edges": [ { "node": { @@ -105,7 +129,7 @@ will return the JSON: ## Polymorphic Many-to-One (MorphTo) -An union type indicates that a field might have multiple object types. +A union type indicates that a field might have multiple object types. ```graphql query { diff --git a/docs/guide/graphql/ordering/index.md b/docs/guide/graphql/sorting/index.md similarity index 66% rename from docs/guide/graphql/ordering/index.md rename to docs/guide/graphql/sorting/index.md index 6cd195b..79684fb 100644 --- a/docs/guide/graphql/ordering/index.md +++ b/docs/guide/graphql/sorting/index.md @@ -1,8 +1,8 @@ --- -title: Ordering +title: Sorting --- -# Ordering +# Sorting ---