API schema about telegram-bot-api HOT 10 CLOSED

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.

from telegram-bot-api.

@levlam,

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.

from telegram-bot-api.

There are no plans to provide documentation in other formats because of their limited flexibility and usefulness.

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:
https://s3.nl-ams.scw.cloud/josxa-content/49/Mtjq236QlL.mp4

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.

from telegram-bot-api.

@levlam

Bots written 5 years ago should still work.

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 ChatMemberMember has no attribute named can_* are no longer in the API.

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".

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
For example i have many patterns to detect returning type, here is some of this:

• Returns (?P<type>[a-z]+)
• (?P<type>[a-z]+) on success
• a (?P<type>[a-z]+) object
• On success, an (?P<type>array of [a-z]+)s that were sent is returned
• (?P<type>[a-z]+) is returned, otherwise (?P<other>[a-z]+) is returned
• returns the edited (?P<type>[a-z]+), otherwise returns (?P<other>[a-z]+)

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.

from telegram-bot-api.

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 ChatMemberMember has no attribute named can_* are no longer in the API.

There were no changes in the Bot API 5.3 in the content of ChatMember JSON object at all. Only documentation was updated to better describe, which fields are specific to which chat member type.

from telegram-bot-api.

@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 can_* fields were marked as optional in the documentation and were never present for the members of the type member as meaningless. The check if member.can_delete_messages was ever wrong, because can_delete_messages field never existed for members of the type "creator" and the check would fail for them, despite their ability to delete others messages.

from telegram-bot-api.

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 ChatMemberMember has no attribute named can_* are no longer in the API.

There were no changes in the Bot API 5.3 in the content of ChatMember JSON object at all. Only documentation was updated to better describe, which fields are specific to which chat member type.

@levlam, you're wrong!

In previous version Telegram libraries built a single ChatMember class based on old version of docs.
And this was correct and worked fine for all my bots.

example

class ChatMember:
    user: User = Field(base=User)
    status: str = Field()
    ...
    can_delete_messages: Optional[bool] = Field()

My bots worked with this library and check can_* fields:

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 can_delete_messages is None (absent). This behaviour is not described neither in old docs nor in new docs.

from telegram-bot-api.

@Hirrolot
Yes, generated API wrappers has limited usefulness. The most important part of a library is how it glues the parts together and what additional functionality it provides. To be usable it is critical for the library to effectively use language-specific features, simplifying its usage. An autogenerated API wrapper can greatly simplify initial library impementation and slightly simplify its updates, but it can also introduce a lot of burden. For example, one of the main features of the Bot API is backward compatibility. Bots written 5 years ago should still work. You don't want to make migration between every minor Bot API/library version painful, but this is very hard to achieve without manual backward compatibility support.

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.

from telegram-bot-api.

'Mm

from telegram-bot-api.

@levlam,

To be usable it is critical for the library to effectively use language-specific features, simplifying its usage.

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

At most one of the optional parameters can be present in any given update.

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.

Generated API wrappers also has limited flexibility.

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.

from telegram-bot-api.