wholetrans/docs-mastodon
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Clarify since_id vs min_id (#1209)

Browse source 
* Clarify since_id vs min_id

* forgot to update the template
This commit is contained in:
trwnh 2023-08-21 09:40:12 -05:00 • committed by GitHub
parent e71fb8b814
commit 5377ff0edf
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
12 changed files with 75 additions and 63 deletions
Download patch file Download diff file Expand all files Collapse all files

24
content/en/api/guidelines.md
View file

@ -32,7 +32,27 @@ With that said, because IDs are string representations of numbers, they can stil
## Paginating through API responses {#pagination}
Many API methods allow you to paginate for more information, using parameters such as `limit`, `max_id`, `min_id`, and `since_id`. However, some of these API methods operate on entity IDs that are not publicly exposed in the API response, and are only known to the backend and the database. (This is usually the case for entities that reference other entities, such as Follow entities which reference Accounts, or Favourite entities which reference Statuses, etc.)
Many API methods allow you to paginate for more information, using parameters such as `limit`, `max_id`, `min_id`, and `since_id`.
limit
: The maximum number of results to return. Usually, there is a default limit and a maximum limit; these will vary according to the API method.
max_id
: String. All results returned will be lesser than this ID. In effect, sets an upper bound on results.
since_id
: String. All results returned will be greater than this ID. In effect, sets a lower bound on results.
min_id
: String. Returns results immediately newer than this ID. In effect, sets a cursor at this ID and paginates forward. (Available since v2.6.0.)
For example, we might fetch `https://mastodon.example/api/v1/accounts/1/statuses` with certain parameters, and we will get the following results in the following cases:
- Setting `?max_id=1` will return no statuses, since there are no statuses with an ID earlier than `1`.
- Setting `?since_id=1` will return the latest statuses, since there have been many statuses since `1`.
- Setting `?min_id=1` will return the oldest statuses, as `min_id` sets the cursor.
Some API methods operate on entity IDs that are not publicly exposed in the API response, and are only known to the backend and the database. (This is usually the case for entities that reference other entities, such as Follow entities which reference Accounts, or Favourite entities which reference Statuses, etc.)
To get around this, Mastodon may return links to a "prev" and "next" page. These links are made available via the HTTP `Link` header on the response. Consider the following fictitious API call:
@ -40,7 +60,7 @@ To get around this, Mastodon may return links to a "prev" and "next" page. These
GET https://mastodon.example/api/v1/endpoint HTTP/1.1
Authorization: Bearer token
Link: <https://mastodon.example/api/v1/endpoint?max_id=7163058>; rel="next", <https://mastodon.example/api/v1/endpoint?since_id=7275607>; rel="prev"
Link: <https://mastodon.example/api/v1/endpoint?max_id=7163058>; rel="next", <https://mastodon.example/api/v1/endpoint?min_id=7275607>; rel="prev"
[
{
// some Entity