Pagination
When a response from the REST API would include many results, Bmining will paginate the results and return a subset of the results. For example, GET /tags/satoshi/addresses
will only return 30 addresses from the satoshi
tag even though the tag includes over 1600 addresses. This makes the response easier to handle for servers and for people.
You can use the link header from the response to request additional pages of data. If an endpoint supports the per_page query parameter, you can control how many results are returned on a page.
This article demonstrates how to request additional pages of results for paginated responses, how to change the number of results returned on each page, and how to write a script to fetch multiple pages of results.
Using link
headers
When a response is paginated, the response headers will include a link header. If the endpoint does not support pagination, or if all results fit on a single page, the link header will be omitted.
The link header contains URLs that you can use to fetch additional pages of results. For example, the previous, next, first, and last page of results.
curl --include --request GET \
--url "https://api.bmining.pro/tags/satoshi/addresses" \
--header "Accept: application/json"
If the response is paginated, the link header will look something like this:
link: <https://api.bmining.pro/tags/satoshi/addresses?page=2>; rel="prev",
<https://api.bmining.pro/tags/satoshi/addresses?page=4>; rel="next",
<https://api.bmining.pro/tags/satoshi/addresses?page=515>; rel="last",
<https://api.bmining.pro/tags/satoshi/addresses?page=1>; rel="first"
The link
header provides the URL for the previous, next, first, and last page of results:
- The URL for the previous page is followed by
rel="prev"
. - The URL for the next page is followed by
rel="next"
. - The URL for the last page is followed by
rel="last"
. - The URL for the first page is followed by
rel="first"
.
Using per_page
query parameter
Some endpoints support the per_page
query parameter. This parameter allows you to specify the number of results to return on a page. The default number of results per page is 30, but some endpoints may have a different default.
For example, the GET /tags/satoshi/addresses
endpoint supports the per_page
query parameter. To request 100 addresses per page, you can use the following request:
curl --include --request GET \
--url "https://api.bmining.pro/tags/satoshi/addresses?per_page=100" \
--header "Accept: application/json"
The URLs in the link
header use query parameters to indicate which page of results to return. The query parameters in the link URLs may differ between endpoints, however each paginated endpoint will use the page
, before/after
, or since
query parameters. (Some endpoints use the since parameter for something other than pagination.) In all cases, you can use the URLs in the link header to fetch additional pages of results.
Changing the number of items per page
If an endpoint supports the per_page
query parameter, then you can control how many results are returned on a page.
For example, this request uses the per_page query parameter to return two items per page:
curl --include --request GET \
--url "https://api.bmining.pro/tags/satoshi/addresses?per_page=2" \
--header "Accept: application/json"
The response will include a link header with the following URLs:
link: <https://api.bmining.pro/tags/satoshi/addresses?page=1&per_page=2>; rel="prev",
<https://api.bmining.pro/tags/satoshi/addresses?page=3&per_page=2>; rel="next",
<https://api.bmining.pro/tags/satoshi/addresses?page=100&per_page=2>; rel="last",
<https://api.bmining.pro/tags/satoshi/addresses?page=1&per_page=2>; rel="first"
The URLs in the link
header use query parameters to indicate which page of results to return. The query parameters in the link URLs may differ between endpoints, however each paginated endpoint will use the page
, before/after
, or since
query parameters. (Some endpoints use the since parameter for something other than pagination.) In all cases, you can use the URLs in the link header to fetch additional pages of results.