​​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.
  • ​​Things that will help the mobile team, need more planning
  • ​​[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.  
  • ​​Etc.
  • ​​[Design] Figure out a new layout for the “Arguments” tables that doesn’t line-wrap awkwardly whenever the “Example” is nontrivial.
  • ​​
​​
​​
​​