Roadmap for "REST API” docs
This document is intended to cover the near-term roadmap of significant projects we should be doing to make the API documentation better.
- Clean up common documentation for REST API (top-level section)
- PR: https://github.com/zulip/zulip/pull/13390. Reorganize/rewrite the sections on “API keys” and “zuliprc files” into a single nice top-level article. Ideally, this would recommend using the “Download zuliprc” feature as the first step for folks using our bindings (and possibly for other use cases), with manually passing environment variables or similar as a secondary path. And then we should add links from other parts of the docs to this page whenever we need to discuss API keys or creating bots.
- Expand the “Error handling” page to have example code for doing error-handling in Python, just in terms of “first you check the status code, then you check code, then you do whatever“ (later can add JS, but let’s focus on making Python nice first since those bindings are 10x more mature). The code under zulip/integrations in python-zulip-api likely has some useful example code we can borrow.
- Explain our “JSON-encoded” encoding strategy clearly (maybe on its own page), so that arguments docs can link to that.
- PR: https://github.com/zulip/zulip/pull/13415. Add a top-level article about language bindings, with links to all of the various language binding projects for Zulip that are out there, communicating clearly which are community-supported vs. core projects. https://chat.zulip.org/#narrow/stream/127-integrations/topic/API.20client.20libraries/near/716010 has some effort at listing them; Google and Tim can help with more.
- Things that will help the mobile team, need more planning
- [Vishnu?] Integrate https://github.com/zulip/zulip/pull/13204; probably not a good project for David
- [Tim to plan] Add some sort of automated verification of the example responses so that they’re never stale.
- Improve the standards for how the individual REST endpoint pages are documented
- We should consistently link to the /help/ articles for the relevant feature for every feature’s API docs, at least where it makes sense to do so.
- PR: https://github.com/zulip/zulip/pull/13455. https://zulipchat.com/api/upload-file should explain that uploading a file doesn’t share it with anyone; you need to then include the URI in a link to it in a Zulip message. Maybe including extending the example code to send a Zulip message containing a proper link to the file.
- [Design] Figure out a new layout for the “Arguments” tables that doesn’t line-wrap awkwardly whenever the “Example” is nontrivial.