From 5377ff0edf075b0584a6d7afae3efef93aa17e0c Mon Sep 17 00:00:00 2001 From: trwnh Date: Mon, 21 Aug 2023 09:40:12 -0500 Subject: [PATCH] Clarify since_id vs min_id (#1209) * Clarify since_id vs min_id * forgot to update the template --- archetypes/methods.md | 8 ++--- content/en/api/guidelines.md | 24 ++++++++++++-- content/en/methods/accounts.md | 8 ++--- content/en/methods/admin/accounts.md | 16 +++++----- content/en/methods/endorsements.md | 3 +- content/en/methods/follow_requests.md | 3 +- content/en/methods/mutes.md | 2 +- content/en/methods/notifications.md | 8 ++--- content/en/methods/scheduled_statuses.md | 8 ++--- content/en/methods/search.md | 12 +++---- content/en/methods/statuses.md | 6 ---- content/en/methods/timelines.md | 40 ++++++++++++------------ 12 files changed, 75 insertions(+), 63 deletions(-) diff --git a/archetypes/methods.md b/archetypes/methods.md index 261db256..ba3ea7f7 100644 --- a/archetypes/methods.md +++ b/archetypes/methods.md @@ -38,14 +38,14 @@ Authorization **Internal parameter.** Use HTTP `Link` header for pagination. -max_id -: String. Return results older than ID. +max_id +: String. All results returned will be lesser than this ID. In effect, sets an upper bound on results. since_id -: String. Return results newer than ID. +: String. All results returned will be greater than this ID. In effect, sets a lower bound on results. min_id -: String. Return results immediately newer than ID. +: String. Returns results immediately newer than this ID. In effect, sets a cursor at this ID and paginates forward. limit : Integer. Maximum number of results to return. Defaults to 20 statuses or 40 accounts. Max twice the default limit. diff --git a/content/en/api/guidelines.md b/content/en/api/guidelines.md index ad14480b..a3a526a0 100644 --- a/content/en/api/guidelines.md +++ b/content/en/api/guidelines.md @@ -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: ; rel="next", ; rel="prev" +Link: ; rel="next", ; rel="prev" [ { // some Entity diff --git a/content/en/methods/accounts.md b/content/en/methods/accounts.md index 3cee3475..5e00972f 100644 --- a/content/en/methods/accounts.md +++ b/content/en/methods/accounts.md @@ -745,14 +745,14 @@ Authorization ##### Query parameters -max_id -: String. Return results older than this ID +max_id +: String. All results returned will be lesser than this ID. In effect, sets an upper bound on results. since_id -: String. Return results newer than this ID +: String. All results returned will be greater than this ID. In effect, sets a lower bound on results. min_id -: String. Return results immediately newer than this ID +: String. Returns results immediately newer than this ID. In effect, sets a cursor at this ID and paginates forward. limit : Integer. Maximum number of results to return. Defaults to 20 statuses. Max 40 statuses. diff --git a/content/en/methods/admin/accounts.md b/content/en/methods/admin/accounts.md index e15a1419..7f53ba32 100644 --- a/content/en/methods/admin/accounts.md +++ b/content/en/methods/admin/accounts.md @@ -83,14 +83,14 @@ ip staff : Boolean. Filter for staff accounts? -max_id -: String. Return results older than ID. +max_id +: String. All results returned will be lesser than this ID. In effect, sets an upper bound on results. since_id -: String. Return results newer than ID. +: String. All results returned will be greater than this ID. In effect, sets a lower bound on results. min_id -: String. Return results immediately newer than ID. +: String. Returns results immediately newer than this ID. In effect, sets a cursor at this ID and paginates forward. limit : Integer. Maximum number of results to return. Defaults to 100 accounts. Max 200 accounts. @@ -233,14 +233,14 @@ email ip : String. Lookup users with this IP address. -max_id -: String. Return results older than ID. +max_id +: String. All results returned will be lesser than this ID. In effect, sets an upper bound on results. since_id -: String. Return results newer than ID. +: String. All results returned will be greater than this ID. In effect, sets a lower bound on results. min_id -: String. Return results immediately newer than ID. +: String. Returns results immediately newer than this ID. In effect, sets a cursor at this ID and paginates forward. limit : Integer. Maximum number of results to return. Defaults to 100 accounts. Max 200 accounts. diff --git a/content/en/methods/endorsements.md b/content/en/methods/endorsements.md index bbedf350..902a313f 100644 --- a/content/en/methods/endorsements.md +++ b/content/en/methods/endorsements.md @@ -29,8 +29,7 @@ Accounts that the user is currently featuring on their profile. **Returns:** Array of [Account]({{< relref "entities/account" >}})\ **OAuth:** User token + `read:accounts`\ **Version history:**\ -2.5.0 - added\ -3.3.0 - both `min_id` and `max_id` can be used at the same time now +2.5.0 - added #### Request diff --git a/content/en/methods/follow_requests.md b/content/en/methods/follow_requests.md index 0ca2d3be..88d8391d 100644 --- a/content/en/methods/follow_requests.md +++ b/content/en/methods/follow_requests.md @@ -27,8 +27,7 @@ GET /api/v1/follow_requests HTTP/1.1 **Returns:** Array of [Account]({{< relref "entities/account" >}})\ **OAuth:** User token + `read:follows` or `follow`\ **Version history:**\ -0.0.0 - added\ -3.3.0 - both `min_id` and `max_id` can be used at the same time now +0.0.0 - added #### Request diff --git a/content/en/methods/mutes.md b/content/en/methods/mutes.md index 6eacfbc5..7a63212d 100644 --- a/content/en/methods/mutes.md +++ b/content/en/methods/mutes.md @@ -30,7 +30,7 @@ Accounts the user has muted. **OAuth:** User token + `read:mutes` or `follow`\ **Version history:**\ 0.0.0 - added\ -3.3.0 - added `mute_expires_at`. both `min_id` and `max_id` can be used at the same time now +3.3.0 - added `mute_expires_at` #### Request ##### Headers diff --git a/content/en/methods/notifications.md b/content/en/methods/notifications.md index 30fc55fe..90193341 100644 --- a/content/en/methods/notifications.md +++ b/content/en/methods/notifications.md @@ -57,14 +57,14 @@ Authorization ##### Query parameters -max_id -: String. Return results older than this ID +max_id +: String. All results returned will be lesser than this ID. In effect, sets an upper bound on results. since_id -: String. Return results newer than this ID +: String. All results returned will be greater than this ID. In effect, sets a lower bound on results. min_id -: String. Return results immediately newer than this ID +: String. Returns results immediately newer than this ID. In effect, sets a cursor at this ID and paginates forward. limit : Integer. Maximum number of results to return. Defaults to 15 notifications. Max 30 notifications. diff --git a/content/en/methods/scheduled_statuses.md b/content/en/methods/scheduled_statuses.md index 75a29ea5..8fa38269 100644 --- a/content/en/methods/scheduled_statuses.md +++ b/content/en/methods/scheduled_statuses.md @@ -39,14 +39,14 @@ Authorization ##### Query parameters -max_id -: String. Return results older than ID. +max_id +: String. All results returned will be lesser than this ID. In effect, sets an upper bound on results. since_id -: String. Return results newer than ID. +: String. All results returned will be greater than this ID. In effect, sets a lower bound on results. min_id -: String. Return results immediately newer than ID. +: String. Returns results immediately newer than this ID. In effect, sets a cursor at this ID and paginates forward. limit : Integer. Maximum number of results to return. Defaults to 20 statuses. Max 40 statuses. diff --git a/content/en/methods/search.md b/content/en/methods/search.md index 5fcc8fe5..81ecac72 100644 --- a/content/en/methods/search.md +++ b/content/en/methods/search.md @@ -59,11 +59,11 @@ account_id exclude_unreviewed : Boolean. Filter out unreviewed tags? Defaults to false. Use true when trying to find trending tags. -max_id -: String. Return results older than this ID. +max_id +: String. All results returned will be lesser than this ID. In effect, sets an upper bound on results. min_id -: String. Return results immediately newer than this ID. +: String. Returns results immediately newer than this ID. In effect, sets a cursor at this ID and paginates forward. limit : Integer. Maximum number of results to return, per type. Defaults to 20 results per category. Max 40 results per category. @@ -188,11 +188,11 @@ resolve account_id : String. If provided, will only return statuses authored by this account. -max_id -: String. Return results older than this ID. +max_id +: String. All results returned will be lesser than this ID. In effect, sets an upper bound on results. min_id -: String. Return results immediately newer than this ID. +: String. Returns results immediately newer than this ID. In effect, sets a cursor at this ID and paginates forward. limit : Integer. Maximum number of results to return, per type. Defaults to 20 results per category. Max 40 results per category. diff --git a/content/en/methods/statuses.md b/content/en/methods/statuses.md index 8b477d52..0640268a 100644 --- a/content/en/methods/statuses.md +++ b/content/en/methods/statuses.md @@ -622,9 +622,6 @@ max_id since_id : **Internal parameter.** Use HTTP `Link` header for pagination. -min_id -: **Internal parameter.** Use HTTP `Link` header for pagination. - limit : Integer. Maximum number of results to return. Defaults to 40 accounts. Max 80 accounts. @@ -696,9 +693,6 @@ max_id since_id : **Internal parameter.** Use HTTP `Link` header for pagination. -min_id -: **Internal parameter.** Use HTTP `Link` header for pagination. - limit : Integer. Maximum number of results to return. Defaults to 40 accounts. Max 80 accounts. diff --git a/content/en/methods/timelines.md b/content/en/methods/timelines.md index 89bca4b7..a8a38f92 100644 --- a/content/en/methods/timelines.md +++ b/content/en/methods/timelines.md @@ -51,14 +51,14 @@ remote only_media : Boolean. Show only statuses with media attached? Defaults to false. -max_id -: String. Return results older than ID. +max_id +: String. All results returned will be lesser than this ID. In effect, sets an upper bound on results. since_id -: String. Return results newer than ID. +: String. All results returned will be greater than this ID. In effect, sets a lower bound on results. min_id -: String. Return results immediately newer than ID. +: String. Returns results immediately newer than this ID. In effect, sets a cursor at this ID and paginates forward. limit : Integer. Maximum number of results to return. Defaults to 20 statuses. Max 40 statuses. @@ -139,14 +139,14 @@ remote only_media : Boolean. Return only statuses with media attachments? Defaults to false. -max_id -: String. Return results older than ID. +max_id +: String. All results returned will be lesser than this ID. In effect, sets an upper bound on results. since_id -: String. Return results newer than ID. +: String. All results returned will be greater than this ID. In effect, sets a lower bound on results. min_id -: String. Return results immediately newer than ID. +: String. Returns results immediately newer than this ID. In effect, sets a cursor at this ID and paginates forward. limit : Integer. Maximum number of results to return. Defaults to 20 statuses. Max 40 statuses. @@ -249,14 +249,14 @@ Authorization ##### Query parameters -max_id -: String. Return results older than ID. +max_id +: String. All results returned will be lesser than this ID. In effect, sets an upper bound on results. since_id -: String. Return results newer than ID. +: String. All results returned will be greater than this ID. In effect, sets a lower bound on results. min_id -: String. Return results immediately newer than ID. +: String. Returns results immediately newer than this ID. In effect, sets a cursor at this ID and paginates forward. limit : Integer. Maximum number of results to return. Defaults to 20 statuses. Max 40 statuses. @@ -325,14 +325,14 @@ Authorization ##### Query parameters -max_id -: String. Return results older than ID. +max_id +: String. All results returned will be lesser than this ID. In effect, sets an upper bound on results. since_id -: String. Return results newer than ID. +: String. All results returned will be greater than this ID. In effect, sets a lower bound on results. min_id -: String. Return results immediately newer than ID. +: String. Returns results immediately newer than this ID. In effect, sets a cursor at this ID and paginates forward. limit : Integer. Maximum number of results to return. Defaults to 20 statuses. Max 40 statuses. @@ -398,14 +398,14 @@ Authorization ##### Query parameters -max_id -: String. Return results older than ID. +max_id +: String. All results returned will be lesser than this ID. In effect, sets an upper bound on results. since_id -: String. Return results newer than ID. +: String. All results returned will be greater than this ID. In effect, sets a lower bound on results. min_id -: String. Return results immediately newer than ID. +: String. Returns results immediately newer than this ID. In effect, sets a cursor at this ID and paginates forward. limit : Integer. Maximum number of results to return. Defaults to 20 statuses. Max 40 statuses.