, (*1)
API Standard based on article d'octo talks, (*2)
[Tradction en cours], (*3)
Installation
composer require enderlab/middle-earth-api-formatter
Description
Format and standardize parameters for a REST API. An attribute "_ api" is created in the "Request" object., (*4)
GET /api/v1/users/1?fields=firstname,lastname,address(city,street)&sort=firstname,lastname,age&desc=age&range=0-10&test=bidule
[_api] => Array(
[fields] => Array(
[0] => firstname
[1] => lastname
[4] => Array(
[address] => Array(
[0] => city
[1] => street
)
)
)
[sort] => Array(
[asc] => Array(
[0] => firstname
[1] => lastname
)
[desc] => Array(
[0] => age
)
)
[range] => Array(
[0] => 0
[1] => 10
)
[filters] => Array(
[test] => bidule
)
)
Parameters
Partial response
Partial response allow clients to retrieve only the information they need, (*5)
GET /api/v1/users/1?fields=firstname,lastname
OR
GET /api/v1/users/1?fields=firstname,lastname,address(city,street)
ApiFormatterMiddleware return an array :, (*6)
[_api] => Array(
[fields] => Array(
[0] => firstname
[1] => lastname
[4] => Array(
[address] => Array(
[0] => city
[1] => street
)
)
)
)
The parameter "range" lets paginate the results., (*7)
Format : range={offset}-{limit}, (*8)
Si "range" ne contient pas les deux paramĂštres {offset} et {limit}, une exception de type
"InvalidArgumentException" est lancée., (*9)
GET /api/v1/users?range=0-10
ApiFormatterMiddleware retournera un tableau :, (*10)
[_api] => Array(
[range] => Array(
[0] => 0 //offset
[1] => 10 //limit
)
)
Tris
Pour les tris, deux paramĂštres sont pris en compte.
- sort : Contient la liste des champs séparés par des virgules
- desc : le tri est croissant par défaut. Pour filtrer de maniÚre descendante, il faudra spécifier
ce paramĂštre (vide pour avoir un tri descendant sur tous les champs contenus dans "sort" ou
vous pouvez définir certain champ contenu dans "sort"), (*11)
// tri ascendant sur les champs firstname,lastname
GET /api/v1/users?sort=firstname,lastname
[_api] => Array(
[sort] => Array(
[asc] => Array(
[0] => firstname
[1] => lastname
)
)
)
// tri descendant sur les champs firstname,lastname
GET /api/v1/users?sort=firstname,lastname&desc
[_api] => Array(
[sort] => Array(
[desc] => Array(
[0] => firstname
[1] => lastname
)
)
)
// tri ascendant sur les champs firstname,lastname et descendant sur le champ age
GET /api/v1/users?sort=firstname,lastname,age&desc=age
[_api] => Array(
[sort] => Array(
[asc] => Array(
[0] => firstname
[1] => lastname
)
[desc] => Array(
[0] => age
)
)
)
Filtres
// Ex : Récupération de tous les users dont le prénom est "john"
GET /api/v1/users?=john
[_api] => Array(
[filters] => Array(
[firstname] => john
)
)
// Ex : Récupération de tous les users dont le prénom est "john" et "david"
GET /api/v1/users?firstname=john,david
[_api] => Array(
[filters] => Array(
[firstname] => [john,david]
)
)