mirror of
https://github.com/AnimeThemes/animethemes-api-docs.git
synced 2026-11-13 17:49:54 +01:00
docs(graphql): add validation section (#134)
This commit is contained in:
Kyrch authored and GitHub committed
1 parent
b9cd7b09a4
commit
8a5b9d5e4c
6 files changed
+106
-48
No files matched your search
@@ -567,6 +567,7 @@ export default {
|
||||
{ text: 'Filtering', link: '/graphql/guide/filtering/' },
|
||||
{ text: 'Sorting', link: '/graphql/guide/sorting/' },
|
||||
{ text: 'Relationships', link: '/graphql/guide/relationships/' },
|
||||
{ text: 'Validation', link: '/graphql/guide/validation' },
|
||||
],
|
||||
},
|
||||
{
|
||||
|
||||
@@ -6,19 +6,7 @@ title: Filtering
|
||||
|
||||
---
|
||||
|
||||
Most queries provide filtering arguments using the AND operator. Filtering arguments are built using the `{field}_{filter}` pattern.
|
||||
|
||||
## Filter Arguments
|
||||
|
||||
| Name | Fields | Example | Description |
|
||||
| :-----: | :--------------------------------------------: | :--------: | ----------------------------------------------- |
|
||||
| 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 |
|
||||
|
||||
Most queries provide some filtering arguments using the AND operator. Filtering arguments are built using the `{field}_{filter}` case pattern.
|
||||
|
||||
Query example:
|
||||
```graphql
|
||||
@@ -56,8 +44,8 @@ It supports single conditions, logical operators, and nested filters.
|
||||
query {
|
||||
animePagination(
|
||||
where: {
|
||||
field: SEASON,
|
||||
operator: NE,
|
||||
column: SEASON,
|
||||
operator: NEQ,
|
||||
value: FALL
|
||||
}
|
||||
) {
|
||||
@@ -81,12 +69,12 @@ query {
|
||||
where: {
|
||||
OR: [
|
||||
{
|
||||
field: SEASON,
|
||||
column: SEASON,
|
||||
operator: EQ,
|
||||
value: WINTER,
|
||||
},
|
||||
{
|
||||
field: SEASON,
|
||||
column: SEASON,
|
||||
operator: EQ,
|
||||
value: FALL,
|
||||
}
|
||||
@@ -101,19 +89,21 @@ query {
|
||||
}
|
||||
```
|
||||
|
||||
::: info
|
||||
Aggregate filters (such as count/exists) do not work when combined with logical operators.
|
||||
:::
|
||||
|
||||
### Comparison Operators
|
||||
|
||||
| Value | Description |
|
||||
| :-----: | :----------------------------------------------------------------------------- |
|
||||
| EQ | Matches values that are exactly equal to the given value. |
|
||||
| NE | Matches values that are not equal to the given value. |
|
||||
| LT | Matches values less than the given value. |
|
||||
| GT | Matches values greater than the given value. |
|
||||
| LTE | Matches values less than or equal to the given value. |
|
||||
| GTE | Matches values greater than or equal to the given value. |
|
||||
| LIKE | Matches values that partially match the given pattern (using wildcard search). |
|
||||
| NOTLIKE | Matches values that do not match the given pattern. |
|
||||
| Value | Description |
|
||||
| :---------: | :----------------------------------------------------------------------------- |
|
||||
| EQ | Matches values that are exactly equal to the given value. |
|
||||
| NEQ | Matches values that are not equal to the given value. |
|
||||
| LT | Matches values less than the given value. |
|
||||
| GT | Matches values greater than the given value. |
|
||||
| LTE | Matches values less than or equal to the given value. |
|
||||
| GTE | Matches values greater than or equal to the given value. |
|
||||
| LIKE | Matches values that partially match the given pattern (using wildcard search). |
|
||||
| NOT_LIKE | Matches values that do not match the given pattern. |
|
||||
| IN | Matches values that are within the given values. |
|
||||
| NOT_IN | Matches values that are not within the given values. |
|
||||
| BETWEEN | Matches values that are within a range of the given values. |
|
||||
| NOT_BETWEEN | Matches values that are not within a range of the given values. |
|
||||
| IS_NULL | Matches values that are null. |
|
||||
| IS_NOT_NULL | Matches values that are not null. |
|
||||
@@ -54,18 +54,4 @@ 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
|
||||
}
|
||||
}
|
||||
```
|
||||
@@ -26,7 +26,7 @@ The following query
|
||||
```graphql
|
||||
query {
|
||||
animePagination(first: 2, page: 1) {
|
||||
paginationInfo {
|
||||
paginatorInfo {
|
||||
count
|
||||
currentPage
|
||||
firstItem
|
||||
|
||||
@@ -55,7 +55,14 @@ query {
|
||||
name
|
||||
series {
|
||||
pageInfo { # Pagination
|
||||
hasNextPage
|
||||
hasPreviousPage
|
||||
startCursor
|
||||
endCursor
|
||||
total
|
||||
count
|
||||
currentPage
|
||||
lastPage
|
||||
}
|
||||
nodes { # Without pivot fields
|
||||
name
|
||||
@@ -79,7 +86,14 @@ will return the JSON:
|
||||
"name": "Hibike! Euphonium",
|
||||
"series": {
|
||||
"pageInfo": {
|
||||
"total": 1
|
||||
"hasNextPage": false,
|
||||
"hasPreviousPage": false,
|
||||
"startCursor": "MQ==",
|
||||
"endCursor": "MQ==",
|
||||
"total": 1,
|
||||
"count": 1,
|
||||
"currentPage": 1,
|
||||
"lastPage": 1
|
||||
},
|
||||
"nodes": [
|
||||
{
|
||||
@@ -112,7 +126,14 @@ query {
|
||||
name
|
||||
resources {
|
||||
pageInfo { # Pagination
|
||||
hasNextPage
|
||||
hasPreviousPage
|
||||
startCursor
|
||||
endCursor
|
||||
total
|
||||
count
|
||||
currentPage
|
||||
lastPage
|
||||
}
|
||||
nodes { # Without pivot fields
|
||||
link
|
||||
@@ -137,7 +158,14 @@ will return the JSON:
|
||||
"name": "Hibike! Euphonium",
|
||||
"resources": {
|
||||
"pageInfo": {
|
||||
"total": 9
|
||||
"hasNextPage": false,
|
||||
"hasPreviousPage": false,
|
||||
"startCursor": "MQ==",
|
||||
"endCursor": "OQ==",
|
||||
"total": 9,
|
||||
"count": 9,
|
||||
"currentPage": 1,
|
||||
"lastPage": 1
|
||||
},
|
||||
"nodes": [
|
||||
{
|
||||
|
||||
@@ -0,0 +1,53 @@
|
||||
---
|
||||
title: Validation
|
||||
---
|
||||
|
||||
# Validation
|
||||
|
||||
---
|
||||
|
||||
The AnimeThemes GraphQL API follows the [GraphQL official error handling specification](https://graphql.org/learn/response/#errors).
|
||||
|
||||
Whenever a validation error occurs, the API will still return an HTTP 200 status code. Instead of relying on status codes to indicate failure, errors are reported in the `errors` array within the response body.
|
||||
|
||||
Validation can fail for several reasons, including:
|
||||
|
||||
* An invalid query structure
|
||||
* Missing required arguments
|
||||
* Incorrect argument types or values
|
||||
|
||||
### Example
|
||||
|
||||
Consider the `findAnimeByExternalSite` query. This query requires at least one of the following arguments to function properly: `id` or `link`.
|
||||
|
||||
If neither argument is provided, the API will return an HTTP 200 response with an errors array describing the validation issue, similar to the following JSON:
|
||||
|
||||
```json
|
||||
{
|
||||
"errors": [
|
||||
{
|
||||
"message": "The id field is required when link is not present. (and 1 more error)",
|
||||
"locations": [
|
||||
{
|
||||
"line": 2,
|
||||
"column": 2
|
||||
}
|
||||
],
|
||||
"path": [
|
||||
"findAnimeByExternalSite"
|
||||
],
|
||||
"extensions": {
|
||||
"validation": {
|
||||
"id": [
|
||||
"The id field is required when link is not present."
|
||||
],
|
||||
"link": [
|
||||
"The link field is required when id is not present."
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Reference in new issue
Block a user