Query Syntax
The interface that is exposed by the schemas to the API clients works primarily with query parameters. This guide explains this query syntax for each of the parameters.
All of the syntax examples below are based on the schema below. Don't worry
about some weird design decisions (an id
and a uuid
?); it's just an example.
<?php
namespace App\Schemas;
use Apitizer\Validation\Rules;
use Illuminate\Database\Eloquent\Model;
class UserSchema extends \Apitizer\Schema
{
public function fields(): array
{
return [
'id' => $this->int('id'),
'uuid' => $this->uuid('uuid'),
'title' => $this->string('title')->description('wow'),
'body' => $this->string('body'),
'status' => $this->enum('status', PostStatus::all()),
'created_at' => $this->datetime('created_at')->format(),
'updated_at' => $this->datetime('updated_at')->format(),
];
}
public function associations(): array
{
return [
'author' => $this->association('author', UserSchema::class),
'comments' => $this->association('comments', CommentSchema::class)
->description('People always have an opinion.'),
'tags' => $this->association('tags', TagSchema::class),
];
}
public function filters(): array
{
return [
'search' => $this->filter()->search('name'),
'status' => $this->filter()->expect()->array()
->whereEach()->enum(PostStatus::all())->byField('status'),
];
}
public function sorts(): array
{
return [
'id' => $this->sort()->byField('id'),
'name' => $this->sort()->byField('name'),
];
}
public function rules(Rules $rules): array
{
}
public function model(): Model
{
return new \App\Models\User();
}
}
Fields and associations
Sparse fieldsets is a concept that should be familiar to anyone that has ever
worked with GraphQL or JSON-API. The syntax for Apitizer's fields
parameter is
based on PostgREST.
To select only specific fields:
?fields=id,uuid,title,status
Associations can also be selected, including nested associations:
?fields=id,title,author(id,name),comments(id,body,author(id,name))
Whitespace between fields is allowed and will be automatically trimmed. The following two are equal:
?fields=id, title, author(id,name)
?fields=id,title,author(id,name)
Expressions may be quoted using "
:
?fields=id," preserve spaces "
Quoted expressions may also contain "reserved" letters. So the following
expression will be considered as two fields: id
and author(id,name)
. It will
not interpret the author as an association.
?fields=id,"author(id,name)"
Fields may also be passed as a list, but you lose the ability to select associations:
?fields[]=id&fields[]=title&fields[]=status
Filters
Filters follow the same syntax as JSON-API:
?filters[name_of_filter]=value
?filters[search]=term
?filters[created_before]=2020-01-01
?filters[user]=ed69bc2f-58ef-44bd-bfdb-5adcac43b6b9
Filters may also accept an array of values:
?filters[status][]=draft&filters[status][]=published
Sorting
Sorting accepts one or many fields, together with an optional modifier. The modifier defaults to "asc" for ascending order.
?sort=name.asc
?sort=name
?sort=id.desc,name.asc
Sorting may also be an array:
?sort[]=name.asc&sort[]=id.desc