Clone this wiki locally
WARNING! STILL IN DEVELOPMENT!
The pages linked here document the unfinished WebNews "v1" API, which will eventually replace the current "v0" API documented elsewhere. Everything here is subject to change, typically with notifications posted to
csh.web in the event of breaking changes. Keep in mind that even though the API v1 is served from a separate "staging" site, it still operates on the live production news server. Avoid making posts outside the
csh.test groups unless necessary, and clean up any messes you make.
CSH WebNews is a RESTful web service that sits on top of a local NNTP server, providing access to both the underlying news articles and several newsreader-like features (unread post tracking, starring, etc.) via a JSON interface. It uses CSH's Stanford Webauth setup to identify users, and OAuth 2 for authentication.
Clients must specify the version of the API they want to use. The current and only version of the API is v1. Any changes made to this version will remain backward-compatible with the original specification. Incompatible changes will only be introduced in new versions, unless such changes are necessary to close a security vulnerability.
Cases where the observed behavior of the API differs from this documentation should be reported as bugs on the issue tracker. Violations of the versioning policy described above should also be reported. Security issues should be disclosed privately when possible.
Testing the API
Resty is a good tool for sending test requests to the API interactively on the command line. It can be set up to always use the same headers and base URL, avoiding excessive line editing or copy-pasting.
- API: General Usage – Base URL, required headers, data formats, etc.
- API: Authentication – App registration, OAuth usage and supported flows