beetbox / beetbox/beets

Design and prototype new HTTP API

Open
#736 5 comments 0 reactions 0 assignees View on GitHub
feature
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.