Versioning in the API is supported by so-called TL layers.
The need to add a new object constructor or to add/remove a field in a constructor creates a backwards compatibility problem for previous versions of API clients. After all, simply changing a constructor in a schema also changes its number. To address this problem, each schema update is separated into a layer.
A layer is a collection of updated methods or constructors in a TL schema. Each layer is numbered with sequentially increasing numbers starting with 2. The first layer is the base layer -- the TL schema without any changes.
There is a helper method to let the API know that a client supports the Layer layer:
invokeWithLayer#da9b0d0d {X:Type} layer:int query:!X = X;The helper method invokeWithLayer can be used only together with initConnection: the present layer will be saved with all other parameters of the client and any future requests will be using this saved value. See more below.
It is possible to save information about the current client on the server in conjunction with an authorization key. This may help eliminate client-side problems with certain releases on certain devices or with certain localizations, as well as eliminate the need for sending layer information in each request.
The helper method initConnection accepts client parameters. This method must be called when first calling the API after the application has restarted or in case the value of one of the parameters could have changed.
initConnection must also be called after each auth.bindTempAuthKey.
When calling this method, the current layer used by the client is also saved (the layer in which initConnection was wrapped is used). After a successful call to initConnection it is no longer necessary to wrap each API call in invokeWithLayerN.
invokeWithoutUpdates#bf9459b7 {X:Type} query:!X = X;invokeWithoutUpdates can be used to invoke a request without subscribing the used connection for updates (this is enabled by default for file queries).
By default, the server processes parallel requests in arbitrary order. Two helper methods exist for cases when the client needs certain requests to be processed in a certain order and intends to send a new request before the previous one is completed:
invokeAfterMsg#cb9f372d {X:Type} msg_id:long query:!X = X;
invokeAfterMsgs#3dc4b4f0 {X:Type} msg_ids:Vector
They may be used, for example, when a client attempts to send messages that accumulated while waiting for the Internet connection to be restored for a long time. In this case, the 32-bit number 0xcb9f372d must be added before the method number in each request, followed by a 64-bit message identifier, msg_id, which contains the previous request in the queue.
The second method is similar, except it takes several messages that must be successfully processed before the current one.
If the waiting period exceeds 0.5 seconds (this value may change in the future) and no result has appeared, the method will return the 400 MSG_WAIT_TIMEOUT error.
Important: if the helper methods invokeAfterMsg / invokeAfterMsgs are used together with invokeWithLayerN or other helper methods, invokeAfterMsg / invokeAfterMsgs must always be the outermost wrapper.
We recommend using gzip compression when calling methods to reduce the amount of network traffic.
The schema and constructor information are given in the protocol documentation.
Before transmitting a query, the string containing the entire body of the serialized high-level query (starting with the method number) must be compressed using gzip. If the resulting string is smaller than the original, it makes sense to transmit the gzip_packed constructor.
There is no point in doing the above when transmitting binary multimedia data (photos, videos) or small messages (up to 255 bytes).
By default, the server compresses the response to any request as well as updates, in accordance with the rules stated above. If the gzip_packed constructor is received as a response in rpc_result, then the string that follows must be extracted and uncompressed. Processing then continues on the resulting new string.