Design and prototype new HTTP API
- Dominant language
- Python
- Stars
- 15.7k
- Forks
- 2.1k
- Avg merge
- 4d 21h
- Merged PRs (30d)
- 31
Description
This is a subtask of the next-generation web interface effort (#718).
We should start designing the new JSON/REST API. We can start with code or documentation first (whichever's easiest). But here's how I propose we go about it:
- To avoid bikeshedding, let's follow the [JSON API](http://jsonapi.org) template.
- Implement the prototype as a new beets plugin called `serve` (i.e., `beetsplug/serve.py`). We will probably eventually roll this into beets core, but a plugin is a good place to play for now. The API should be documented in `docs/plugins/serve.rst`.
- We should place an emphasis on generality. Where reasonable, the API should be useful for non-beets tools. In spirit, the API could serve as a better (and better-documented!) alternative to DAAP, DLNA, or Subsonic for music browsing and streaming.
- No need for backwards compatibility with the old API.
- The prototype plugin should not have an HTML frontend. It should only expose the machine-readable API.
Here are some proposed requirements for the new API design:
- [ ] Look up and query tracks, albums, and maybe artists (just like the current API).
- [ ] Stream music files (again, like the current API).
- [ ] Optional authentication. Options include HTTP basic with token acquisition, OAuth, etc.
- [ ] Provide extension points for other functionality not listed here. I'm not sure what form this should come in, but the extensibility should _at least_ afford an REST API to the importer. Other extensions to be kept in mind include:
- Server-side playback control.
- Server-side transcoding for browser playback.
- [ ] A mechanism for mounting browser frontends. This is important because, without some support, the single-origin policy will prevent HTML frontends hosted elsewhere from accessing the HTTP API. We can do this either by serving up user-specified HTML pages on the server itself or by using [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS) to permit access. (Note that this is more a part of the prototype implementation than the API itself.)
Anything else to add?
Contributor guide
Assessment
This issue has not been assessed yet.