From 2fb4723fe41aa89099195899b9ae1c2b31f0aa02 Mon Sep 17 00:00:00 2001 From: Kyrch Date: Fri, 8 Aug 2025 00:38:53 -0300 Subject: [PATCH] docs(graphql): paginator suffix & singular queries (#119) --- .../examples/filter-by-external-site/index.md | 18 ++-- docs/graphql/guide/filtering/index.md | 18 ++-- docs/graphql/guide/getting-started/index.md | 22 ++++- docs/graphql/guide/pagination/index.md | 6 +- docs/graphql/guide/relationships/index.md | 97 +++++++++---------- docs/graphql/guide/sorting/index.md | 20 ++-- 6 files changed, 91 insertions(+), 90 deletions(-) diff --git a/docs/graphql/examples/filter-by-external-site/index.md b/docs/graphql/examples/filter-by-external-site/index.md index 8f10902..2f04da8 100644 --- a/docs/graphql/examples/filter-by-external-site/index.md +++ b/docs/graphql/examples/filter-by-external-site/index.md @@ -7,20 +7,18 @@ title: 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. +The `findAnimeByExternalSite` query accepts three arguments to filter anime by external resources. +An external resource may be linked to multiple anime. ## Query Example ```graphql query ($id: Int!) { - { - findAnimesByExternalSite(site: ANILIST, id: $id) { - name - mediaFormat - season - year - } + findAnimeByExternalSite(site: ANILIST, id: $id) { + name + mediaFormat + season + year } } ``` @@ -42,7 +40,7 @@ None ```json { "data": { - "findAnimesByExternalSite": [ + "findAnimeByExternalSite": [ { "name": "Hibike! Euphonium 3", "mediaFormat": "TV", diff --git a/docs/graphql/guide/filtering/index.md b/docs/graphql/guide/filtering/index.md index c459227..848866f 100644 --- a/docs/graphql/guide/filtering/index.md +++ b/docs/graphql/guide/filtering/index.md @@ -23,7 +23,7 @@ Most queries provide filtering arguments using the AND operator. Filtering argum Query example: ```graphql query { - animes(name_like: "%monogatari%") { + animePaginator(name_like: "%monogatari%") { data { name } @@ -47,7 +47,7 @@ The argument is `trashed: Trashed`, which allows filtering to determine if trash ```graphql query { - animes(trashed: ONLY) { + animePaginator(trashed: ONLY) { data { name } @@ -61,14 +61,12 @@ Filtering in relationships is applied **ONLY** to the relationship and does not ```graphql query { - animes { - data { - name - animethemes(type: OP) { - data { - type - sequence - } + anime(slug: "hibike_euphonium") { + name + animethemes(type: OP) { + data { + type + sequence } } } diff --git a/docs/graphql/guide/getting-started/index.md b/docs/graphql/guide/getting-started/index.md index 18508e6..5327582 100644 --- a/docs/graphql/guide/getting-started/index.md +++ b/docs/graphql/guide/getting-started/index.md @@ -20,7 +20,7 @@ The AnimeThemes API needs a `Content-Type` header. # A simple curl request works like this. curl -X POST -H "Content-Type: application/json" - -d "{\"query\": \"{ animes { data { name } } }\"}" + -d "{\"query\": \"{ animePaginator { data { name } } }\"}" https://graphql.animethemes.moe/ ``` @@ -28,12 +28,12 @@ curl -X POST ### Top Level -The AnimeThemes API specifies a custom `data` wrap for top-level members. +The AnimeThemes API specifies a custom `data` wrap for top-level members that use pagination. The following query ```graphql query { - animes { + animePaginator { data { name } @@ -44,7 +44,7 @@ will return the JSON: ```json { "data": { - "animes": { + "animePaginator": { "data": [ { "name": ".hack//Liminality" @@ -54,4 +54,18 @@ will return the JSON: } } } +``` + +### Singular Query + +In case you want to return a single object, there are a few types that allow it. +The following example returns the first anime with the slug hibike_euphonium. + +```graphql +query { + anime(slug: "hibike_euphonium") { + name + slug + } +} ``` \ No newline at end of file diff --git a/docs/graphql/guide/pagination/index.md b/docs/graphql/guide/pagination/index.md index 45872b2..901874c 100644 --- a/docs/graphql/guide/pagination/index.md +++ b/docs/graphql/guide/pagination/index.md @@ -8,6 +8,8 @@ title: Pagination The AnimeThemes API query that uses pagination shall contain a `paginatorInfo` object for pagination strategies and a `data` collection with the resources. +The top-level fields that use pagination are singular and have the `Paginator` suffix. + ## Arguments @@ -23,7 +25,7 @@ There are two arguments available for every query that uses pagination. The following query ```graphql query { - animes(first: 2, page: 1) { + animePaginator(first: 2, page: 1) { paginatorInfo { count currentPage @@ -44,7 +46,7 @@ will return the JSON: ```json { "data": { - "animes": { + "animePaginator": { "paginatorInfo": { "count": 2, "currentPage": 1, diff --git a/docs/graphql/guide/relationships/index.md b/docs/graphql/guide/relationships/index.md index e77a634..07dbbc1 100644 --- a/docs/graphql/guide/relationships/index.md +++ b/docs/graphql/guide/relationships/index.md @@ -16,7 +16,7 @@ A many-to-one relationship has an object that references the foreign type. ```graphql query { - animethemes { + animethemePaginator { data { sequence anime { @@ -33,13 +33,11 @@ A one-to-many relationship has a list of objects that reference the related type ```graphql query { - animes { - data { - name - animethemes(first: 2) { - data { - sequence - } + anime(slug: "hibike_euphonium") { + name + animethemes(first: 2) { + data { + sequence } } } @@ -66,24 +64,22 @@ Both fields `createdAt` and `updatedAt` are available for every many-to-many rel The following query ```graphql query { - animes { - data { - name - resources { - pageInfo { # Pagination - total - } - nodes { # Without pivot fields + anime(slug: "hibike_euphonium") { + name + resources { + pageInfo { # Pagination + total + } + nodes { # Without pivot fields + link + } + edges { # With pivot fields + node { link } - edges { # With pivot fields - node { - link - } - as - createdAt - updatedAt - } + as + createdAt + updatedAt } } } @@ -93,35 +89,30 @@ will return the JSON: ```json { "data": { - "animes": { - "data": [ - { - "name": ".hack//Liminality", - "resources": { - "pageInfo": { - "total": 6 + "anime": { + "name": "Hibike! Euphonium", + "resources": { + "pageInfo": { + "total": 9 + }, + "nodes": [ + { + "link": "https://myanimelist.net/anime/27989" + }, + ... + ], + "edges": [ + { + "node": { + "link": "https://myanimelist.net/anime/27989" }, - "nodes": [ - { - "link": "https://myanimelist.net/anime/299" - }, - ... - ], - "edges": [ - { - "node": { - "link": "https://myanimelist.net/anime/299" - }, - "as": null, - "createdAt": "2021-03-27T00:46:24+00:00", - "updatedAt": "2021-03-27T00:46:24+00:00" - } - ... - ] + "as": null, + "createdAt": "2021-03-26T21:49:16+00:00", + "updatedAt": "2021-03-26T21:49:16+00:00" } - } - ... - ] + ... + ] + } } } } @@ -133,7 +124,7 @@ A union type indicates that a field might have multiple object types. ```graphql query { - performances { + performancePaginator { data { artist { ... on Artist { @@ -159,7 +150,7 @@ The inverse relationship of polymorphic many-to-one. Applies pagination. ```graphql query { - memberships { + membershipPaginator { data { performances { data { diff --git a/docs/graphql/guide/sorting/index.md b/docs/graphql/guide/sorting/index.md index 0c92023..53bcc71 100644 --- a/docs/graphql/guide/sorting/index.md +++ b/docs/graphql/guide/sorting/index.md @@ -16,14 +16,14 @@ To sort in descending order, append `_DESC` to the field name. ## Query ```graphql -{ - animes(sort: NAME) { # Sorting in ascending direction. +query { + animePaginator(sort: NAME) { # Sorting in ascending direction. data { name } } - animes(sort: NAME_DESC) { # Sorting in descending direction. + animePaginator(sort: NAME_DESC) { # Sorting in descending direction. data { name } @@ -36,13 +36,11 @@ To sort in descending order, append `_DESC` to the field name. It is possible to sort the relationships of the parent type. ```graphql -{ - animes { - data { - resources(sort: EXTERNAL_ID) { - nodes { - externalId - } +query { + anime(slug: "hibike_euphonium") { + resources(sort: EXTERNAL_ID) { + nodes { + externalId } } } @@ -55,7 +53,7 @@ By providing a list of enum cases, the sort will be applied in the order of the ```graphql { - animes(sort: [YEAR_DESC, SEASON]) { + animePaginator(sort: [YEAR_DESC, SEASON]) { data { year season