Clarify since_id vs min_id (#1209)

* Clarify since_id vs min_id

* forgot to update the template

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.

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: <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

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.

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.

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
 

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
 

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

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.

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.

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.

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.
 

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.