Skip to content

Commit

Permalink
add pagination ref, limit text to 80 chars per row
Browse files Browse the repository at this point in the history
  • Loading branch information
ktsypkina committed Oct 4, 2023
1 parent 53488ab commit cc96d62
Showing 1 changed file with 32 additions and 18 deletions.
50 changes: 32 additions & 18 deletions chapters/http-requests.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -457,42 +457,56 @@ Query parameters should have the following aspects specified:
* Comparison semantics (equals, less than, greater than, etc)
* Implications when combined with other queries, e.g. _and_ vs. _or_

How query parameters are named and used is up to individual API designers, here are
a few tips that could help to decide whether to use simple or more complex query language:
1. Consider using simple query language when API is built to be used by others (external teams):
How query parameters are named and used is up to individual API designers, here
are a few tips that could help to decide whether to use simple or more complex
query language:
1. Consider using simple query language when API is built to be used
by others (external teams):
* no additional effort/logic to form the query
* no ambiguity in meaning of the query parameters (e.g. in GET /items?user_id=gt:100 user_id is greater than 100 or userId is equal to gt:100?)
* no ambiguity in meaning of the query parameters. For example
in GET /items?user_id=gt:100 user_id is greater than 100 or
userId is equal to gt:100?
* easy to read, no learning curve

2. For internal usage or specific use case a more complex query language can be used
(such as `price gt 10` or `price[gt]=10` or `price>10` etc.). Also please consider
following #237 guidance for designing complex query languages with JSON.
2. For internal usage or specific use case a more complex query language can
be used (such as `price gt 10` or `price[gt]=10` or `price>10` etc.).
Also please consider following #237 guidance for designing complex query
languages with JSON.

The following examples should serve as ideas for simple query language:

*Equals*
* `name=Zalando`, `creation_year=2023`, `updated_by=user1` - query elements based on property equality
* `created_at=2023-09-18T12:12:00.000Z`, `sort=id:desc` - query elements based on logical properties
* `color=red,green,blue,multicolored` - query elements based on multiple choice possibility
** for these type of filters consider to use #237 guidance to have smth like filters={"color":["red","green","blue"]}
* `name=Zalando`, `creation_year=2023`, `updated_by=user1`
(query elements based on property equality)
* `created_at=2023-09-18T12:12:00.000Z`, `sort=id:desc`
(query elements based on logical properties)
* `color=red,green,blue,multicolored`
(query elements based on multiple choice possibility)
** for these type of filters consider to use #237 guidance to have
smth like filters={"color":["red","green","blue"]}

*Less than*
* `max_length=5` - query elements based on upper and lower bounds (`min` and `max`)
* `max_length=5` - query elements based on upper/lower bounds (`min` and `max`)
* `shorter_than=5` - query elements using terminology specific e.g. to _length_
* `price_lower_than=50` or `price_lower_than_or_equal=50`
* `created_before=2019-07-17` or `active_until=2023-09-18T12:12:00.000Z`
** Using terminology specific e.g. to time: _before_, _after_, _since_ and _until_
** Using terminology specific to time: _before_, _after_, _since_ and _until_

*More than*
* `min_length=2` - query elements based on upper and lower bounds (`min` and `max`)
* `min_length=2` - query elements based on upper/lower bounds (`min` and `max`)
* `created_after=2019-07-17` or `modified_since=2019-07-17`
** Using terminology specific e.g. to time: _before_, _after_, _since_ and _until_
** Using terminology specific to time: _before_, _after_, _since_ and _until_
* `price_higher_than=50` or `price_equal_or_higher_than=50`

*Pagination*
* `offset=10` and `limit=5` - query elements for pagination regardless customer sorting
* `limit=5` and `created_after=2019-07-17` - query elements for keyset pagination
** when sorting is in place and new elements are inserted it prevents to show same results due to offset shift
* `offset=10` and `limit=5`
(query elements for pagination regardless customer sorting)
* `limit=5` and `created_after=2019-07-17`
(query elements for keyset pagination)
** when sorting is in place and new elements are inserted it prevents to show
same results due to offset shift.
Please refer to <<137, conventional query parameters for pagination and sorting>>
and you can also find additional info in <<pagination>> section below.

We don't advocate for or against certain names because in the end
APIs should be free to choose the terminology that fits their domain the best.
Expand Down

0 comments on commit cc96d62

Please sign in to comment.