API v1

Alex Grant edited this page Jul 4, 2015 · 3 revisions

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.

Versioning

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.

Issue Reports

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.

Overview Documentation

Endpoint Documentation