Add documentation for developing new features against the API

[neiljp]

Description of documentation

• There is quite extensive documentation available on subsystems, at least in terms of the server implementation; that's not all directly applicable to us, but it can trickle down into the API
• The API docs (chat.zulip.org/api/) themselves can be very useful; that includes a lot of useful pages, but in particular
  • the /api/changelog for variation between server versions (fine-grained zulip feature levels, ZFL in ZT)
  • the /api/real-time-events API, including /api/register-queue and /api/get-events
  • the endpoints where we perform an action, eg. /api/send-message, /api/get-messages, ...
• Sample bots and a framework for them are in the python-zulip-api repo, along with the python zulip API wrapper and a botserver; the bot framework is a much simplified API interface (there's been discussion on whether to keep it or port some helpers into the main API wrapper library instead). We could mention this as a way to

This should include how our current architecture would preferably involve obtaining the initial data and keeping it up to date using events, display it in the app, then possibly allowing use of additional endpoints to modify the data - which will feed back to the app via the events.

This can also mention the version parity: n labels and relate that to the API changelog, as well as adding tests for different versions of the server.

Somewhere we should also ensure that it is clear what different versions exist and how they connect, which again relates to the changelog, namely:

• chat.zulip.org (community server)
• self-hosted servers (could be running any version, particularly if old/not-updated/air-gapped)
• Zulip cloud (different to chat.zulip.org and self-hosted)

This was discussed in a private conversation during GSoC 2024, but has come up previously, motivating this issue.