API schema #41
Comments
|
https://core.telegram.org/bots/api is the primary source for Bot API documentation. There are no plans to provide documentation in other formats because of their limited flexibility and usefulness. |
Formalised documentation formats allow Telegram libraries authors to easily generate API wrappers without the need for custom documentation parsers of https://core.telegram.org/bots/api. Currently, there is a numerous amount of those parsers. Building them is cumbersome and even error-prone. |
|
@hirrolot Generated API wrappers also has limited flexibility. For example, it is hard to conveniently express the API for the file uploading: to upload a file, you can specify a file_id (String), a url (String), an attach name ("attach://..." String), a local path ("file:..." String) or the file itself (uploaded using multipart/form-data). Most of the API can be expressed straightforward, but there are a lot of other hard to express parts. If you feel that you need a formalized documentation format, you can use an already existing documentation parsers. As you correctly said, "there is a numerous amount of those parsers". We may provide an official API schema in one of well-established formats in the future, but currently this is not a priority. |
|
'Mm |
It's a good point, I agree. Some programming languages expose convenient mechanisms for alternative data representations (e.g. sum types). Telegram Bots API makes heavy use of them. For example,
However, it's impossible to programme a parser that distinguishes alternatives. Because of this, in teloxide we have forced to encode all the API types by hand. If we had a formal notation for alternatives right in Telegram Bots API, the types could be generated programmatically.
Yes, like any formal system. A possible solution here is to express "easy-to-express" things formally and "hard-to-express" things informally, in English. This way people could automate some part of API wrapper generation, as you said, at least at the beginning of development. |
Wow, this statement alone has me extremely triggered, I'm sorry. Let me just leave a short video here that shows what kind of workflows are possible when there exists a well-documented OpenAPI schema: How can it be that a random HTML website is preferred over a machine-readable interface specification? How come just about any bot API library maintainer needs to resort to manually updating models, methods, parameters, and corresponding types every couple months, and why is it that there are tons of scrapers for this one unstructured documentation page out there that will cause headaches for everyone involved - between parsers having to be fixed and adjusted and users desperately waiting for their favorite library to update to the latest layer... I am speechless. |
This is an incorrect statement, since the last API update broke compatibility with bots that checked individual fields of the ChatMember object and some of the fields like
I have made one of Bot API docs parser and parsing the returns statements is painful because has no static schema of API methods description with their returning type
And that is not all patterns. I'm not asking you to write OpenAPI schema, i'm asking you to make docs more formalized and easier to parsing. Anyone who needs an OpenAPI scheme can generate it for themselves, but the headache can be relieved. |
There were no changes in the Bot API 5.3 in the content of |
@levlam, you're wrong! In previous version Telegram libraries built a single ChatMember class based on old version of docs. exampleclass ChatMember:
user: User = Field(base=User)
status: str = Field()
...
can_delete_messages: Optional[bool] = Field()My bots worked with this library and check if member.can_delete_messages:
print("Can delete messages")
else:
print("Can't delete messages")It doesn't matter the role of member, matters is he able to delete message or not. Now my code prints "Can't delete messages" for owner, cause |
|
@Olegt0rr You are very wrong. You are talking about a specific wrapper and classes generated by it. There were no changes to the objects provided by Bot API, which you can clearly see by examining its source code. Previously all |
Will someday we have API schema like OpenAPI or custom JSON Schema?
The text was updated successfully, but these errors were encountered: