Most App.net API endpoints that return lists of objects are paginated. Understanding how paginated data is requested and returned is key to retrieving data efficiently from the API.
App.net always returns items from newest to oldest. You paginate through results by passing before_id and since_id to the API which restricts the range of content App.net will return. By adjusting these parameters, you can consistently fill in the data you’re missing from the App.net API.
By default, when you request data App.net will return the most recent items that are older than before_id. If instead you’d like the least recent items that are newer than since_id, you can specify count as a negative value. As an example, if a stream contains:
10, 9, 8, 7, 6, 5, 4, 3, 2, 1
requesting it with before_id=9&since_id=2&count=2 returns
8, 7
requesting it with before_id=9&since_id=2&count=-2 returns
4, 3
In summary:
before_id and since_id define the range App.net will return results from. If provided, they should be filled in from a previous request’s min_id or max_id.pagination_id attribute. This attribute is NOT unique for the individual item but it is unique per (user, api endpoint) pair. For example, if user 2 follows user 1 and subscribes to channel 1, user 2 will appear in both results for Users subscribed to a channel and Users following a user. But, the pagination_ids for user 2 in each of those responses will be different.count tells App.net how many items you want. It defaults to 20 and cannot be more than 200.count is negative, App.net returns results starting from the since_id. Remember, items are always returned from newest to oldest even in this case.
Requests for paginated streams can optionally be filtered by passing the following query string parameters along with the request:
| Name | Description |
|---|---|
since_id |
Return objects following the max_id provided in the response metadata of a previous query or following one of the special pagination ids for streams with Stream Markers. |
before_id |
Return objects preceding the min_id provided in the response metadata of a previous query or preceding one of the special pagination ids for streams with Stream Markers. |
count |
The number of objects to return, up to a maximum of 200. If this value is negative, items will be returned starting at since_id. Please see the pagination overview for more information. |
When requesting objects from an endpoint that supports Stream Markers, you can pass the following special values to the since_id and before_id pagination parameters:
| Value | Description |
|---|---|
last_read |
Use the last_read_id of the current Stream Marker (if there is one) as the value. |
last_read_inclusive |
Use the last_read_id of the current Stream Marker (if there is one) as the value. Also include the "last read" object. |
marker |
Use the id of the current Stream Marker (if there is one) as the value. |
marker_inclusive |
Use the id of the current Stream Marker (if there is one) as the value. Also include the "marked" object. |
Responses from paginated streams will include the following fields in the meta object of the response envelope.
| Name | Type | Description |
|---|---|---|
max_id |
string | The greatest ID returned in the data set. Inclusive. This should be considered an opaque identifier that may be passed as since_id in the next call in order to retrieve the next set of objects. |
min_id |
string | The least ID returned in the data set. Inclusive. This should be considered an opaque identifier that may be passed as before_id in the next call in order to retrieve the previous set of objects. |
more |
boolean | If more is true, there are more matches available for the given query than would fit within count objects. If more is false, there are no more matches available. |