api

Documentation

Overview

Package api provides the RESTful API of the wavepipe media server.

Index

• Constants
• Variables
• func APIInfo(w http.ResponseWriter, r *http.Request)
• func DeleteUsers(w http.ResponseWriter, r *http.Request)
• func GetAlbums(w http.ResponseWriter, r *http.Request)
• func GetArt(w http.ResponseWriter, r *http.Request)
• func GetArtists(w http.ResponseWriter, r *http.Request)
• func GetFolders(w http.ResponseWriter, r *http.Request)
• func GetSearch(w http.ResponseWriter, r *http.Request)
• func GetSongs(w http.ResponseWriter, r *http.Request)
• func GetStatus(w http.ResponseWriter, r *http.Request)
• func GetStream(w http.ResponseWriter, r *http.Request)
• func GetTranscode(w http.ResponseWriter, r *http.Request)
• func GetUsers(w http.ResponseWriter, r *http.Request)
• func GetWaveform(w http.ResponseWriter, r *http.Request)
• func HTTPStream(song *data.Song, mimeType string, contentLength int64, inputStream io.Reader, ...) error
• func PostLastFM(w http.ResponseWriter, r *http.Request)
• func PostLogin(w http.ResponseWriter, r *http.Request)
• func PostLogout(w http.ResponseWriter, r *http.Request)
• func PostUsers(w http.ResponseWriter, r *http.Request)
• func PutUsers(w http.ResponseWriter, r *http.Request)
• func ServeArt(w http.ResponseWriter, r *http.Request, art *data.Art) error
• type AlbumsResponse
• type ArtistsResponse
• type Error
• type ErrorResponse
• type FoldersResponse
• type Information
• type LastFMResponse
• type LoginResponse
• type SearchResponse
• type SongsResponse
• type StatusResponse
• type UsersResponse

Constants

const (
	// Version is the current version of the API
	Version = "v0"
	// Documentation provides a link to the current API documentation
	Documentation = "https://github.com/philpennock/wavepipe/blob/master/doc/API.md"

	// CtxRender is the key used to store a render instance in gorilla context
	CtxRender = "middleware_render"
	// CtxUser is the key used to store a User instance in gorilla context
	CtxUser = "data_user"
	// CtxSession is the key used to store a Session instance on gorilla context
	CtxSession = "data_session"
)

Variables

var (
	// ErrCannotSeek is returned when the input stream is not seekable
	ErrCannotSeek = errors.New("httpStream: cannot seek input stream")
	// ErrInvalidRange is returned when the client attempts to retrieve an out-of-bounds part of the stream
	ErrInvalidRange = errors.New("httpStream: invalid range")
)

var (
	// ErrInvalidIntegerSize is returned when the input size parameter is not
	// a valid integer.
	ErrInvalidIntegerSize = errors.New("invalid integer size")

	// ErrNegativeIntegerSize is returned when a negative integer is passed
	// for the input size parameter.
	ErrNegativeIntegerSize = errors.New("negative integer size")
)

Functions

func APIInfo

func APIInfo(w http.ResponseWriter, r *http.Request)

APIInfo returns information about the API, including the current API version, the supported API versions, and a link to API documentation.

func DeleteUsers

func DeleteUsers(w http.ResponseWriter, r *http.Request)

DeleteUsers deletes users from the wavepipe API, and returns a HTTP status and JSON.

func GetAlbums

func GetAlbums(w http.ResponseWriter, r *http.Request)

GetAlbums retrieves one or more albums from wavepipe, and returns a HTTP status and JSON. It can be used to fetch a single album, a limited subset of albums, or all albums, depending on the request parameters.

func GetArt

func GetArt(w http.ResponseWriter, r *http.Request)

GetArt retrieves a binary art file from wavepipe, optionally resizing the art file. On success, this API will return binary art. On failure, it will return a JSON error.

func GetArtists

func GetArtists(w http.ResponseWriter, r *http.Request)

GetArtists retrieves one or more artists from wavepipe, and returns a HTTP status and JSON. It can be used to fetch a single artist, a limited subset of artists, or all artists, depending on the request parameters.

func GetFolders

func GetFolders(w http.ResponseWriter, r *http.Request)

GetFolders retrieves one or more folders from wavepipe, and returns a HTTP status and JSON. It can be used to fetch a single folder, a limited subset of folders, or all folders, depending on the request parameters.

func GetSearch

func GetSearch(w http.ResponseWriter, r *http.Request)

GetSearch searches for artists, albums, songs, and folders matching a specified search query, and returns a HTTP status and JSON.

func GetSongs

func GetSongs(w http.ResponseWriter, r *http.Request)

GetSongs retrieves one or more songs from wavepipe, and returns a HTTP status and JSON. It can be used to fetch a single song, a limited subset of songs, a specified number of random songs, or all songs, depending on the request parameters.

func GetStatus

func GetStatus(w http.ResponseWriter, r *http.Request)

GetStatus returns the current server status, and optionally, server metrics, with an HTTP status and JSON.

func GetStream

func GetStream(w http.ResponseWriter, r *http.Request)

GetStream a raw, non-transcoded, media file stream from wavepipe. On success, this API will return a binary stream. On failure, it will return a JSON error.

func GetTranscode

func GetTranscode(w http.ResponseWriter, r *http.Request)

GetTranscode returns a transcoded media file stream from wavepipe. On success, this API will return a binary transcode. On failure, it will return a JSON error.

func GetUsers

func GetUsers(w http.ResponseWriter, r *http.Request)

GetUsers retrieves one or more users from wavepipe, and returns a HTTP status and JSON. It can be used to fetch a single user, or all users, depending on the request parameters.

func GetWaveform

func GetWaveform(w http.ResponseWriter, r *http.Request)

GetWaveform generates and returns a waveform image from wavepipe. On success, this API will return a binary stream. On failure, it will return a JSON error.

func HTTPStream

func HTTPStream(song *data.Song, mimeType string, contentLength int64, inputStream io.Reader, req *http.Request, res http.ResponseWriter) error

HTTPStream provides a common method to transfer a file stream using a HTTP response writer

func PostLastFM

func PostLastFM(w http.ResponseWriter, r *http.Request)

PostLastFM allows access to the Last.fm API, enabling wavepipe to set a user's currently-playing track, as well as to enable scrobbling.

func PostLogin

func PostLogin(w http.ResponseWriter, r *http.Request)

PostLogin creates a new session for the input user to use the wavepipe API, and returns a HTTP status and JSON.

func PostLogout

func PostLogout(w http.ResponseWriter, r *http.Request)

PostLogout destroys an existing session from the wavepipe API, and returns a HTTP status and JSON.

func PostUsers

func PostUsers(w http.ResponseWriter, r *http.Request)

PostUsers creates a new user for the wavepipe API, and returns a HTTP status and JSON.

func PutUsers

func PutUsers(w http.ResponseWriter, r *http.Request)

PutUsers updates users on the wavepipe API, and returns a HTTP status and JSON.

func ServeArt

func ServeArt(w http.ResponseWriter, r *http.Request, art *data.Art) error

ServeArt provides a common method for serving and resizing Art, based on an input HTTP request.

Types

type AlbumsResponse

type AlbumsResponse struct {
	Error  *Error       `json:"error"`
	Albums []data.Album `json:"albums"`
	Songs  []data.Song  `json:"songs"`
}

AlbumsResponse represents the JSON response for the Albums API.

type ArtistsResponse

type ArtistsResponse struct {
	Error   *Error        `json:"error"`
	Artists []data.Artist `json:"artists"`
	Albums  []data.Album  `json:"albums"`
	Songs   []data.Song   `json:"songs"`
}

ArtistsResponse represents the JSON response for the Artists API.

type Error

type Error struct {
	Code    int    `json:"code"`
	Message string `json:"message"`
}

Error represents an error produced by the API

type ErrorResponse

type ErrorResponse struct {
	Error *Error `json:"error"`
}

ErrorResponse represents the JSON response for endpoints which only return an error

type FoldersResponse

type FoldersResponse struct {
	Error      *Error        `json:"error"`
	Folders    []data.Folder `json:"folders"`
	Subfolders []data.Folder `json:"subfolders"`
	Songs      []data.Song   `json:"songs"`
}

FoldersResponse represents the JSON response for the Folders API.

type Information

type Information struct {
	Error         *Error   `json:"error"`
	Version       string   `json:"version"`
	Supported     []string `json:"supported"`
	Documentation string   `json:"documentation"`
}

Information represents information about the API

type LastFMResponse

type LastFMResponse struct {
	Error *Error `json:"error"`
	URL   string `json:"url"`
}

LastFMResponse represents the JSON response for the Last.fm API

type LoginResponse

type LoginResponse struct {
	Error   *Error        `json:"error"`
	Session *data.Session `json:"session"`
}

LoginResponse represents the JSON response for /api/logins

type SearchResponse

type SearchResponse struct {
	Error   *Error        `json:"error"`
	Artists []data.Artist `json:"artists"`
	Albums  []data.Album  `json:"albums"`
	Songs   []data.Song   `json:"songs"`
	Folders []data.Folder `json:"folders"`
}

SearchResponse represents the JSON outponse for /api/search

type SongsResponse

type SongsResponse struct {
	Error *Error      `json:"error"`
	Songs []data.Song `json:"songs"`
}

SongsResponse represents the JSON response for the Songs API.

type StatusResponse

type StatusResponse struct {
	Error   *Error           `json:"error"`
	Status  *common.Status   `json:"status"`
	Metrics *metrics.Metrics `json:"metrics"`
}

StatusResponse represents the JSON response for /api/status

type UsersResponse

type UsersResponse struct {
	Error *Error      `json:"error"`
	Users []data.User `json:"users"`
}

UsersResponse represents the JSON response for the Users API.