Pagination¶
Flama provides a built-in mechanism to paginate API responses. This pagination comes with multiple flavors, such as page-based pagination and limit-offset pagination.
Apply pagination to any API endpoint is as easy as apply a decorator to the view itself and Flama will handle the rest, including required parameters and wrapping the response into a paginated response.
Page-based Pagination¶
This pagination technique consists of specifying a page number and page size to define the exact window that should be returned.
from flama import Flama, pagination
app = Flama()
@app.route("/number/", methods=["GET"])
@pagination.page_number
def numbers(**kwargs):
return list(range(100))
Every paginated response automatically includes three new parameters:
- page: the number of the page (default
1
). - page_size: the number of elements for each page (default
10
). - count: a boolean to request the total number of elements as part of the response (default
True
).
The response schema is also modified to include some relevant metadata regarding of pagination status along with the
response data itself. The modified responses consists of a data
section with the expected data and a meta
section
with following attributes:
- page: the number of the page.
- page_size: the number of elements for each page.
- count: the total number of elements.
Examples¶
Some requests examples based on above endpoint.
Default request¶
GET https://flama.server/number/
{
"data": [
0,
1,
2,
3,
4,
5,
6,
7,
8,
9
],
"meta": {
"page_size": 10,
"count": 100,
"page": 1
}
}
Specific page¶
GET https://flama.server/number/?page=2
{
"data": [
10,
11,
12,
13,
14,
15,
16,
17,
18,
19
],
"meta": {
"page_size": 10,
"count": 100,
"page": 2
}
}
Different page size¶
GET https://flama.server/number/?page_size=2
{
"data": [
0,
1
],
"meta": {
"page_size": 2,
"count": 100,
"page": 1
}
}
Avoid counting elements¶
GET https://flama.server/number/?count=false
{
"data": [
0,
1,
2,
3,
4,
5,
6,
7,
8,
9
],
"meta": {
"page_size": 10,
"count": null,
"page": 1
}
}
Page-based Pagination¶
This pagination technique consists of specifying a limit number of items to retrieve and the offset from the start of the collection to define the exact window that should be returned.
import string
from flama import Flama, pagination
app = Flama()
@app.route("/alphabet/", methods=["GET"])
@pagination.limit_offset
def alphabet(**kwargs):
return list(string.ascii_lowercase)
Every paginated response automatically includes three new parameters:
- limit: the maximum number of elements to retrieve (default
10
). - offset: the index of the starting element (default
0
). - count: a boolean to request the total number of elements as part of the response (default
True
).
The response schema is also modified to include some relevant metadata regarding of pagination status along with the
response data itself. The modified responses consists of a data
section with the expected data and a meta
section
with following attributes:
- limit: the maximum number of elements to retrieve.
- offset: the index of the starting element.
- count: the total number of elements.
Examples¶
Some requests examples based on above endpoint.
Default request¶
GET https://flama.server/alphabet/
{
"data": [
"a",
"b",
"c",
"d",
"e",
"f",
"g",
"h",
"i",
"j"
],
"meta": {
"count": 26,
"offset": 0,
"limit": 10
}
}
Using offset¶
GET https://flama.server/alphabet/?offset=5
{
"data": [
"f",
"g",
"h",
"i",
"j",
"k",
"l",
"m",
"n",
"o"
],
"meta": {
"count": 26,
"offset": 5,
"limit": 10
}
}
Different limit¶
GET https://flama.server/alphabet/?limit=2
{
"data": [
"a",
"b"
],
"meta": {
"count": 26,
"offset": 0,
"limit": 2
}
}
Avoid counting elements¶
GET https://flama.server/alphabet/?count=false
{
"data": [
"a",
"b",
"c",
"d",
"e",
"f",
"g",
"h",
"i",
"j"
],
"meta": {
"count": null,
"offset": 0,
"limit": 10
}
}