diff --git a/data/web/blogfork.telegram.org/api/offsets.html b/data/web/blogfork.telegram.org/api/offsets.html index 30eebe17ea..94311046e8 100644 --- a/data/web/blogfork.telegram.org/api/offsets.html +++ b/data/web/blogfork.telegram.org/api/offsets.html @@ -47,28 +47,26 @@

Lots of Telegram API methods provide access to potentially large lists of objects, which requires pagination.

In order to fetch only relevant subset of results for each request there is a number of available input parameters. Here is a list in order how they are applied in API.

Typically, results are returned in reverse chronological order with descending object ID values.

-

limit parameter

+

limit parameter

A limit on the number of objects to be returned, typically between 1 and 100. When 0 is provided the limit will often default to an intermediate value like ~20.

-

offset-based pagination

+

offset-based pagination

For a few methods with mostly static data this parameter allows to skip offset elements from the beginning of list; negative values are ignored.

-

offset_id-based pagination

+

offset_id-based pagination

For most methods where results are real-time data (e.g. any chat history) offset value is not passed directly. Instead it is calculated from the passed offset_id and add_offset parameter values as offsetFromID(offset_id) + add_offset, where offsetFromID(offset_id) is a number of results from the beginning of list up to the result with ID offset_id, inclusive.

Sample use cases:

-

Additional filtering

+
messages.getHistory({offset_id: MSGID, add_offset: 0, limit: 20})
+ +
messages.getHistory({offset_id: MSGID, add_offset: -20, limit: 20})
+ +
messages.getHistory({offset_id: MSGID, add_offset: -10, limit: 20})
+

Additional filtering

There is a number of parameters, which are applied to the list after slicing with offset and limit, to reduce the result subset even more:

-

Hash generation

-

To further reduce the result subset, there is a mechanism to avoid fetching data if the resulting list hasn't changed from the one stored on client, similar to ETag.

+

Hash generation

+

To further reduce the result subset, there is a mechanism to avoid fetching data if the resulting list hasn't changed from the one stored on client, similar to ETag.

When the client has cached results for API request, it can calculate the hash value for it by taking the result IDs (message IDs or other fields with name id) and using them to compute a 64-bit hash with the following algorithm:

# Here, ^ indicates a bitwise XOR
 
 hash = 0
 for id in ids:
-    hash = hash ^ (id >> 21)
-    hash = hash ^ (id << 35)
-    hash = hash ^ (id >> 4)
+    hash = hash ^ (hash >> 21)
+    hash = hash ^ (hash << 35)
+    hash = hash ^ (hash >> 4)
     hash = hash + id

In some cases, the result container already has a hash field, that can be used instead.

When the client passes a correct value, the API will return one of *NotModified constructors, e.g. messages.messagesNotModified instead of the actual results.

-

Example methods

+

Example methods

+ + diff --git a/data/web/core.telegram.org/api/offsets.html b/data/web/core.telegram.org/api/offsets.html index 30eebe17ea..94311046e8 100644 --- a/data/web/core.telegram.org/api/offsets.html +++ b/data/web/core.telegram.org/api/offsets.html @@ -47,28 +47,26 @@

Lots of Telegram API methods provide access to potentially large lists of objects, which requires pagination.

In order to fetch only relevant subset of results for each request there is a number of available input parameters. Here is a list in order how they are applied in API.

Typically, results are returned in reverse chronological order with descending object ID values.

-

limit parameter

+

limit parameter

A limit on the number of objects to be returned, typically between 1 and 100. When 0 is provided the limit will often default to an intermediate value like ~20.

-

offset-based pagination

+

offset-based pagination

For a few methods with mostly static data this parameter allows to skip offset elements from the beginning of list; negative values are ignored.

-

offset_id-based pagination

+

offset_id-based pagination

For most methods where results are real-time data (e.g. any chat history) offset value is not passed directly. Instead it is calculated from the passed offset_id and add_offset parameter values as offsetFromID(offset_id) + add_offset, where offsetFromID(offset_id) is a number of results from the beginning of list up to the result with ID offset_id, inclusive.

Sample use cases:

-

Additional filtering

+
messages.getHistory({offset_id: MSGID, add_offset: 0, limit: 20})
+ +
messages.getHistory({offset_id: MSGID, add_offset: -20, limit: 20})
+ +
messages.getHistory({offset_id: MSGID, add_offset: -10, limit: 20})
+

Additional filtering

There is a number of parameters, which are applied to the list after slicing with offset and limit, to reduce the result subset even more:

-

Hash generation

-

To further reduce the result subset, there is a mechanism to avoid fetching data if the resulting list hasn't changed from the one stored on client, similar to ETag.

+

Hash generation

+

To further reduce the result subset, there is a mechanism to avoid fetching data if the resulting list hasn't changed from the one stored on client, similar to ETag.

When the client has cached results for API request, it can calculate the hash value for it by taking the result IDs (message IDs or other fields with name id) and using them to compute a 64-bit hash with the following algorithm:

# Here, ^ indicates a bitwise XOR
 
 hash = 0
 for id in ids:
-    hash = hash ^ (id >> 21)
-    hash = hash ^ (id << 35)
-    hash = hash ^ (id >> 4)
+    hash = hash ^ (hash >> 21)
+    hash = hash ^ (hash << 35)
+    hash = hash ^ (hash >> 4)
     hash = hash + id

In some cases, the result container already has a hash field, that can be used instead.

When the client passes a correct value, the API will return one of *NotModified constructors, e.g. messages.messagesNotModified instead of the actual results.

-

Example methods

+

Example methods

+ +