servel333/GUIDE.MD

## GUIDE.MD

      
    Raw
  

              GUIDE.MD
            
          
    Motivation

There is no clear standard (or this is a "yet another"?) for formatting query string parameters for various applications in an API.
Problems

Specify model attributes to filter on


&attribute[ATTRIBUTE-NAME]=ATTRIBUTE-VALUE

Specify model attributes to filter on with operators


Operators: greater than, greater than or equal, less than, less than or equal, in, etc...
&attribute[ATTRIBUTE-NAME][OPERATOR]=ATTRIBUTE-VALUE (Proposed)
&attribute[updated-at][gte]=2020-01-01 > SELECT ... WHERE updated-at >= DATE(2020-01-01)
&attribute[ATTRIBUTE-NAME]=[OPERATOR]ATTRIBUTE-VALUE (Proposed)
&attribute[ATTRIBUTE-NAME]=OPERATOR=ATTRIBUTE-VALUE (Proposed)
&attribute[updated-at]=gte=2020-01-01 > SELECT ... WHERE updated-at >= DATE(2020-01-01)
&attribute[categories][in]=a,b,c > SELECT ... WHERE categories IN [a, b, c]
&where[ATTRIBUTE-NAME]=ATTRIBUTE_VALUE

Specify model attributes to return in response body


&field[MODEL-NAME]=ATTRIBUTE-NAME
&field[]=ATTRIBUTE-NAME (Implies primary model name)
&field[]=name&field[]=updated-at > SELECT name, updated-at FROM ...
RULE: The model primary key (Typically id) is implied and always returned.

Include related models in response body


&include[]=MODEL-NAME&include[]=MODEL-NAME
&include=MODEL-NAME,MODEL-NAME

Pagination


&page[offset]=PAGE-OFFSET&page[limit]=PAGE-LIMIT
&page[token]=TOKEN
RULE: Next and previous page links are returned in the response body

Support nested attributes in all params


&attribute[ATTRIBUTE-NAME][ATTRIBUTE-NAME]=ATTRIBUTE-VALUE
&attribute[ATTRIBUTE-NAME.ATTRIBUTE-NAME]=ATTRIBUTE-VALUE

Support querying by date


Require ISO 8601 format

Header to indicate query string parameter format


X-Query-Parameter-Type: application/vnd.standard-qsp.draft-1
X-Query-Parameter-Type: application/vnd.standard-qsp.v1

Examples


/users?includes=orders&fields=id,email&fields[orders]=id,user-id,total,item-count

Notes


How data is returned in the response body is up to the API implementation.

Use of underscore (_)

Apparenty underscore (_) is not liked in the query.
$ curl "localhost:3000/tests/echo?attribute[updated_at][gte]=2020-01-01"
curl: (3) bad range in URL position 37:
localhost:3023/tests/echo?attribute[updated_at][gte]=2020-01-01
References


RFC3986
Wikipedia:URL

{SCHEME}://{USERINFO}@{HOST}:{PORT}/{PATH}?{QUERY}#{FRAGMENT}


cloud.google.com: HTTP headers and common query string parameters for JSON
JSONAPI v1.1

/?page[offset]=0&page[limit]=10


encodeURI


Not Escaped: A-Z a-z 0-9 ; , / ? : @ & = + $ - _ . ! ~ * ' ( ) #

encodeURIComponent


Not Escaped A-Z a-z 0-9 - _ . ! ~ * ' ( )

JSONAPI


Implementation specific query parameters MUST adhere to the same constraints as member names with the additional requirement that they MUST contain at least one non a-z character (U+0061 to U+007A). It is RECOMMENDED that a U+002D HYPHEN-MINUS, “-“, U+005F LOW LINE, “_”, or capital letter is used (e.g. camelCasing).


If a server encounters a query parameter that does not follow the naming conventions above, and the server does not know how to process it as a query parameter from this specification, it MUST return 400 Bad Request.

restdb


?q={"name" : {"$not" : "Joe"}}
?q={"name" : {"$in" : ["Joe", "Jane", "Donald"]}}
?q={"name" : {"$nin" : ["Joe", "Jane", "Donald"]}}
?q={"name" : {"$regex" : ".Joe*"}}
?q={"$or": [{"name": "Jane"}, {"name": "Donald"}]}
?q={"$and": [{"name": "Jane"}, {"last-name": "Cassidy"}]}
$not: Negation logical operator {"field" : {"$not" : val}}
$in: Match any value in array  {"field" : {"$in" : [value1, value2, ...]}}
$nin: Not match any value in array  {"field" : {"$nin" : [value1, value2, ...]}}
$regex: Match field {"field" : {"$regex" : ".*"}}
$or: Logical operator  {"$or": [{"status": "GOLD"}, {"status": "SILVER"}]}
$and: Logical operator {"$and": [{"status": "GOLD"}, {"sales": 1000}]}
?q={"salary": {"$gt": 10000}}
?q={"salary": {"$gte": 10000}}
?q={"salary": {"$lt": 10000}}
?q={"salary": {"$lte": 10000}}
?q={"salary": {"$bt": [5000, 7500]}}
?q={"field": {"$exists": true}}
?q={"field.0": {"$exists": true}}
?q={"contact":{"$elemMatch":{"name":"Anderson", age:35}}}
?q={"$distinct": "age"}&sort=age
$gt > {"salary": {"$gt": 10000}}
$gte  >=  {"salary": {"$gte": 10000}}
$lt < {"salary": {"$lt": 10000}}
$lte  <=  {"salary": {"$lte": 10000}}
$bt >= value <= {"salary": {"$bt": [5000, 7500]}}
$exists Check if field exists {"field": {"$exists": true|false}}
$exists (array) Check if array field exists or is empty {"field.0": {"$exists": true|false}}
$elemMatch Array element matching  {"contact":{"$elemMatch":{"name":"Anderson", age:35}}}
$distinct Array with unique element values  {"$distinct": "name"}
between two dates {"_changed":{"$gt":{"$date":"2016-08-01"},"$lt":{"$date":"2016-08-05"}}}
older than the time just now {"startat":{"$lt":{"$date":"$now"}}}
$now  just now
$currentMinute  start of last minute
$currentHour  start of last hour
$currentDate  start of current day
$today  start of current day
$tomorrow start of next day
$yesterday  start of day before
$currentWeek  start of this week (sunday)
$currentMonth start of this month
$currentYear  start of this year
$nextWeek start of next week (sunday)
$nextMonth  start of next month
$nextYear start of next year