Ampache REST API

RESTful Resource Path Conversion in Ampache

As part of the ongoing modernisation of the Ampache API, the project has created a fully resource-oriented RESTful specification aligned with OpenAPI based on the query-parameter based RPC model.

The OpenApi spec is documented here Ampache REST API

This document explains:

• The differences between the RPC API and the RESTful API
• How resource path conversion works
• Updated endpoint structure and behaviour
• HTTP method alignment
• Versioning model
• Migration guidance

Background

Ampache historically exposed its API through two server entry points providing XML and JSON output formats:

https://demo.ampache.dev/server/xml.server.php?action={action_name}&parameter=value
https://demo.ampache.dev/server/json.server.php?action={action_name}&parameter=value

While functional, this approach:

• Mixes transport and action logic
• Encodes behaviour inside query parameters
• Overloads GET for state-changing operations
• Limits proper HTTP semantics
• Reduces cache effectiveness
• Complicates OpenAPI documentation

The new RESTful API resolves these issues by introducing structured, versioned resource paths.

RPC API Structure

Pattern

{ampacheURL}/server/{format}.server.php?action={action}&{parameters}

Characteristics:

• Behaviour determined by the action parameter
• Primarily GET-based
• Resources inferred indirectly
• Verb-style operation naming

Example:

https://demo.ampache.dev/server/xml.server.php?action=song&id=123
https://demo.ampache.dev/server/json.server.php?action=playlist_songs&id=9
https://demo.ampache.dev/server/xml.server.php?action=add_song&playlist=9&song=123

RESTful Resource Path Structure

Key characteristics:

• Resource-oriented URL design
• Plural resource naming
• Hierarchical relationship modelling
• Proper HTTP verb usage
• OpenAPI-compliant specification
• Clear separation between transport and intent

Base Path

All REST urls require the API version and format as part of the base url.

{ampacheURL}/rest/{version}/{format}

e.g. https://demo.ampache.dev/rest/8/json

Resources and Items

You access objects from resource paths.

{ampacheURL}/rest/{version}/{format}/{resource}

e.g. https://demo.ampache.dev/rest/8/json/albums

Resources can them be filtered into individual items.

{ampacheURL}/rest/{version}/{format}/{resource}/{identifier}

e.g. https://demo.ampache.dev/rest/8/json/albums/21

Nested Resource

When you've filtered to an individual resource you can perform actions on that resource or fetch children of the object.

{ampacheURL}/rest/{version}/{format}/{parent}/{id}/{child}

e.g. https://demo.ampache.dev/rest/8/json/albums/21/songs

REST path to RPC call map

If you're struggling to map the new paths to actions this table will allow you to ID the calls you want to make using the old RPC methods.

All REST path URLs are prefixed with the Ampache Base Path to make sure you are given the correct format and version response.

e.g. To make a REST call for 10 random albums your URL would be https://demo.ampache.dev/rest/8/json/albums/?limit=10&sort=rand

HTTP METHOD	REST	RPC action	Alternative action
GET	albums/{album_id}/art	?action=get_art&filter={album_id}&type=album
POST	albums/{album_id}/commands	?action={flag|rate|share|update_art|update_from_tags}&filter={album_id}&type=album
GET	albums/{album_id}/fetch-metadata	?action=get_external_metadata&filter={album_id}&type=album
POST	albums/{album_id}/flag	?action=flag&filter={album_id}&type=album
POST	albums/{album_id}/rate	?action=rate&filter={album_id}&type=album
POST	albums/{album_id}/share	?action=share&filter={album_id}&type=album
GET	albums/{album_id}/songs	?action=album_songs&filter={album_id}&type=album
POST	albums/{album_id}/update-art	?action=update_art&filter={album_id}&type=album
POST	albums/{album_id}/update-tags	?action=update_from_tags&filter={album_id}&type=album
GET	albums/{album_id}	?action=album&filter={album_id}
GET	albums/search	?action=search&type=album `	advanced_search
GET	albums/stats	?action=stats&type=album
GET	albums	?action=albums
GET	artists/{artist_id}/albums	?action=artist_albums&filter={artist_id}
GET	artists/{artist_id}/art	?action=get_art&filter={artist_id}&type=artist
POST	artists/{artist_id}/commands	?action={flag|rate|share|update_art|update_from_tags}&filter={artist_id}&type=artist
GET	artists/{artist_id}/fetch-info	?action=update_artist_info&filter={artist_id}&type=artist
GET	artists/{artist_id}/fetch-metadata	?action=get_external_metadata&filter={artist_id}&type=artist
POST	artists/{artist_id}/flag	?action=flag&filter={artist_id}&type=artist
POST	artists/{artist_id}/rate	?action=rate&filter={artist_id}&type=artist
POST	artists/{artist_id}/share	?action=share&filter={artist_id}&type=artist
GET	artists/{artist_id}/similar	?action=get_similar&filter={artist_id}&type=artist
GET	artists/{artist_id}/songs	?action=artist_songs&filter={artist_id}&type=artist
POST	artists/{artist_id}/update-art	?action=update_art&filter={artist_id}&type=artist
POST	artists/{artist_id}/update-tags	?action=update_from_tags&filter={artist_id}&type=artist
GET	artists/{artist_id}	?action=artist&filter={artist_id}
GET	artists/search	?action=search&type=artist	advanced_search
GET	artists/stats	?action=stats&type=artist
GET	artists	?action=artists
GET	bookmarks/{bookmark_id}	?action=bookmark&filter={bookmark_id}
PATCH	bookmarks/{bookmark_id}	?action=bookmark_edit&filter={bookmark_id}
DELETE	bookmarks/{bookmark_id}	?action=bookmark_delete&filter={bookmark_id}
GET	bookmarks	?action=bookmarks
PUT	bookmarks	?action=bookmark_create&filter={object_id}&type={object_type}
GET	browse	?action=browse
POST	catalogs/{catalog_id}/action	?action=catalog_action&filter={catalog_id}
POST	catalogs/{catalog_id}/add	?action=catalog_action&filter={catalog_id}&task=add_to_catalog
GET	catalogs/{catalog_id}/browse/albums/{album_id}	?action=browse&filter={album_id}&type=album&catalog={catalog_id}
GET	catalogs/{catalog_id}/browse/artists/{artist_id}	?action=browse&filter={artist_id}&type=artist&catalog={catalog_id}
GET	catalogs/{catalog_id}/browse/podcasts/{podcast_id}	?action=browse&filter={podcast_id}&type=podcast&catalog={catalog_id}
GET	catalogs/{catalog_id}/browse	?action=browse&filter={catalog_id}&type=catalog
POST	catalogs/{catalog_id}/clean	?action=catalog_action&filter={catalog_id}&task=clean_catalog
POST	catalogs/{catalog_id}/commands	?action=catalog_action&filter={catalog_id}&task={task}
POST	catalogs/{catalog_id}/file	?action=catalog_file&filter={catalog_id}
POST	catalogs/{catalog_id}/folder	?action=catalog_folder&filter={catalog_id}
POST	catalogs/{catalog_id}/update	?action=catalog_action&filter={catalog_id}&task=update_catalog
POST	catalogs/{catalog_id}/verify	?action=catalog_action&filter={catalog_id}&task=verify_catalog
GET	catalogs/{catalog_id}	?action=catalog&filter={catalog_id}
DELETE	catalogs/{catalog_id}	?action=catalog_delete&filter={catalog_id}
GET	catalogs	?action=catalogs
PUT	catalogs	?action=catalog_create `	catalog_add
POST	democratic/{object_id}/localplay	?action=localplay&command=add&filter={object_id}&type=democratic
POST	democratic/{object_id}	?action=democratic&filter={object_id}
GET	folder	?action=folder
GET	folders	?action=folders
GET	genres/{genre_id}/albums	?action=genre_albums&filter={genre_id}
GET	genres/{genre_id}/artists	?action=genre_artists&filter={genre_id}
GET	genres/{genre_id}/songs	?action=genre_songs&filter={genre_id}
GET	genres/{genre_id}	?action=genre&filter={genre_id}
GET	genres/search	?action=search&type=genre	advanced_search
GET	genres	?action=genres
GET	goodbye	?action=goodbye
GET	handshake	?action=handshake
GET	index	?action=index
GET	labels/{label_id}/artists	?action=label_artists&filter={label_id}
GET	labels/{label_id}/fetch-metadata	?action=get_external_metadata&filter={label_id}&type=label
GET	labels/{label_id}	?action=label&filter={label_id}
GET	labels/search	?action=search&type=label	advanced_search
GET	labels	?action=labels
GET	licenses/{license_id}/songs	?action=license_songs&filter={license_id}
GET	licenses/{license_id}	?action=license&filter={license_id}
GET	licenses	?action=licenses
GET	list	?action=list
POST	live-streams/{live_stream_id}/localplay	?action=localplay&command=add&filter={live_stream_id}&type=live_stream
GET	live-streams/{live_stream_id}	?action=live_stream&filter={live_stream_id}
PATCH	live-streams/{live_stream_id}	?action=live_stream_edit&filter={live_stream_id}
DELETE	live-streams/{live_stream_id}	?action=live_stream_delete&filter={live_stream_id}
GET	live-streams	?action=live_streams
PUT	live-streams	?action=live_stream_create
POST	localplay/add	?action=localplay&command=add&filter={object_id}&type={object_type}
POST	localplay/commands	?action=localplay&command={command}&filter={object_id}&type={object_type}
GET	localplay/delete-all	?action=localplay&command=delete_all
GET	localplay/next	?action=localplay&command=next
POST	localplay/pause	?action=localplay&command=pause
GET	localplay/play	?action=localplay&command=play
GET	localplay/prev	?action=localplay&command=prev
GET	localplay/skip	?action=localplay&command=skip
GET	localplay/status	?action=localplay&command=status
POST	localplay/stop	?action=localplay&command=stop
GET	localplay/volume-down	?action=localplay&command=volume_down
GET	localplay/volume-mute	?action=localplay&command=volume_mute
GET	localplay/volume-up	?action=localplay&command=volume_up
POST	localplay	?action=localplay
GET	me/friends-timeline	?action=friends_timeline
GET	me/last-shouts	?action=last_shouts
GET	me/lost-password	?action=lost_password
GET	me/now-playing	?action=now_playing
GET	me/playlists	?action=user_playlists
GET	me/smartlists	?action=user_smartlists
GET	me	?action=user
GET	ping	?action=ping
POST	playlists/{playlist_id}/add	?action=playlist_add&filter={playlist_id}
GET	playlists/{playlist_id}/art	?action=get_art&filter={playlist_id}&type=playlist
POST	playlists/{playlist_id}/commands	?action={playlist_add|playlist_remove|playlist_remove_song}&filter={playlist_id}
GET	playlists/{playlist_id}/download	?action=download&filter={playlist_id}&type=playlist
POST	playlists/{playlist_id}/flag	?action=flag&filter={playlist_id}
GET	playlists/{playlist_id}/hash	?action=playlist_hash&filter={playlist_id}
POST	playlists/{playlist_id}/rate	?action=rate&filter={playlist_id}
POST	playlists/{playlist_id}/remove-song	?action=playlist_remove_song&filter={playlist_id}&song={song_id}
POST	playlists/{playlist_id}/remove	?action=playlist_remove&filter={playlist_id}&id={object_id}&type={object_type}
POST	playlists/{playlist_id}/share	?action=share&filter={playlist_id}
GET	playlists/{playlist_id}/songs	?action=playlist_songs&filter={playlist_id}
GET	playlists/{playlist_id}/stream	?action=stream&filter={playlist_id}&type=playlist
GET	playlists/{playlist_id}	?action=playlist&filter={playlist_id}
PATCH	playlists/{playlist_id}	?action=playlist_edit&filter={playlist_id}
DELETE	playlists/{playlist_id}	?action=playlist_delete&filter={playlist_id}
GET	playlists/search	?action=search&type=playlist	advanced_search
GET	playlists/stats	?action=stats&type=playlist
GET	playlists	?action=playlists
PUT	playlists	?action=playlist_create
PUT	podcast-episodes/{episode_id}/bookmark	?action=bookmark_create&filter={episode_id}&type=podcast_episode
GET	podcast-episodes/{episode_id}/download	?action=download&filter={episode_id}&type=podcast_episode
POST	podcast-episodes/{episode_id}/flag	?action=flag&filter={episode_id}&type=podcast_episode
POST	podcast-episodes/{episode_id}/localplay	?action=localplay&command=add&filter={episode_id}&type=podcast_episode
POST	podcast-episodes/{episode_id}/playback	?action=player&filter={episode_id}&type=podcast_episode
POST	podcast-episodes/{episode_id}/rate	?action=rate&filter={episode_id}&type=podcast_episode
POST	podcast-episodes/{episode_id}/share	?action=share&filter={episode_id}&type=podcast_episode
GET	podcast-episodes/{episode_id}/stream	?action=stream&filter={episode_id}&type=podcast_episode
GET	podcast-episodes/{episode_id}	?action=podcast_episode&filter={episode_id}
DELETE	podcast-episodes/{episode_id}	?action=podcast_episode_delete&filter={episode_id}
POST	podcast-episodes/{id}/commands	?action={flag|rate|share|player|localplay}&filter={id}&type=podcast_episode
GET	podcast-episodes/deleted	?action=deleted_podcast_episodes
GET	podcast-episodes/search	?action=search&type=podcast_episode	advanced_search
GET	podcast-episodes/stats	?action=stats&type=podcast_episode
GET	podcast-episodes	?action=podcast_episodes
GET	podcasts/{podcast_id}/art	?action=get_art&filter={podcast_id}&type=podcast
POST	podcasts/{podcast_id}/commands	?action={flag|rate|share|podcast_update}&filter={podcast_id}
POST	podcasts/{podcast_id}/flag	?action=flag&filter={podcast_id}
GET	podcasts/{podcast_id}/podcast-episodes	?action=podcast_episodes&filter={podcast_id}
POST	podcasts/{podcast_id}/rate	?action=rate&filter={podcast_id}
POST	podcasts/{podcast_id}/share	?action=share&filter={podcast_id}
POST	podcasts/{podcast_id}/update	?action=podcast_update&filter={podcast_id} `	update_podcast
GET	podcasts/{podcast_id}	?action=podcast&filter={podcast_id}
PATCH	podcasts/{podcast_id}	?action=podcast_edit&filter={podcast_id}
DELETE	podcasts/{podcast_id}	?action=podcast_delete&filter={podcast_id}
GET	podcasts/search	?action=search&type=podcast	advanced_search
GET	podcasts/stats	?action=stats&type=podcast
GET	podcasts	?action=podcasts
PUT	podcasts	?action=podcast_create
GET	preferences/{preference_name}	?action=user_preference&filter={preference_name} `	preferences
PATCH	preferences/{preference_name}	?action=preference_edit&filter={preference_name}
DELETE	preferences/{preference_name}	?action=preference_delete&filter={preference_name}
GET	preferences	?action=user_preferences `	preferences
PUT	preferences	?action=preference_create
POST	register	?action=register
GET	scrobble	?action=scrobble
GET	search/{search_type}/groups	?action=search_group&filter={search_type}
GET	search/{search_type}/rules	?action=search_rules&filter={search_type}
GET	shares/{share_id}	?action=share&filter={share_id}
PATCH	shares/{share_id}	?action=share_edit&filter={share_id}
DELETE	shares/{share_id}	?action=share_delete&filter={share_id}
GET	shares	?action=shares
PUT	shares	?action=share_create
GET	smartlists/{smartlist_id}/art	?action=get_art&filter={smartlist_id}&type=smartlist
GET	smartlists/{smartlist_id}/download	?action=download&filter={smartlist_id}&type=smartlist
POST	smartlists/{smartlist_id}/flag	?action=flag&filter={smartlist_id}&type=smartlist
POST	smartlists/{smartlist_id}/rate	?action=rate&filter={smartlist_id}&type=smartlist
POST	smartlists/{smartlist_id}/share	?action=share&filter={smartlist_id}&type=smartlist
GET	smartlists/{smartlist_id}/songs	?action=smartlist_songs&filter={smartlist_id}
GET	smartlists/{smartlist_id}/stream	?action=stream&filter={smartlist_id}&type=smartlist
GET	smartlists/{smartlist_id}	?action=smartlist&filter={smartlist_id}
DELETE	smartlists/{smartlist_id}	?action=smartlist_delete&filter={smartlist_id}
GET	smartlists/search	?action=search&type=smartlist	advanced_search
GET	smartlists	?action=smartlists
GET	songs/{song_id}/art	?action=get_art&filter={song_id}&type=song
PUT	songs/{song_id}/bookmark	?action=bookmark_create&filter={song_id}&type=song
POST	songs/{song_id}/commands	?action={flag|rate|share|player|record_play|localplay}&filter={song_id}
GET	songs/{song_id}/download	?action=download&filter={song_id}
GET	songs/{song_id}/fetch-metadata	?action=get_external_metadata&filter={song_id}&type=song
POST	songs/{song_id}/flag	?action=flag&filter={song_id}
POST	songs/{song_id}/localplay	?action=localplay&command=add&filter={song_id}&type=song
GET	songs/{song_id}/lyrics	?action=get_lyrics&filter={song_id}
POST	songs/{song_id}/playback	?action=player&filter={song_id}&type=song
POST	songs/{song_id}/rate	?action=rate&filter={song_id}
POST	songs/{song_id}/record-play	?action=record_play&filter={song_id}
POST	songs/{song_id}/share	?action=share&filter={song_id}
GET	songs/{song_id}/similar	?action=get_similar&filter={song_id}&type=song
GET	songs/{song_id}/stream	?action=stream&filter={song_id}&type=song
GET	songs/{song_id}/tags	?action=song_tags&filter={song_id}
POST	songs/{song_id}/update-tags	?action=update_from_tags&filter={song_id}&type=song
GET	songs/{song_id}	?action=song&filter={song_id}
DELETE	songs/{song_id}	?action=song_delete&filter={song_id}
GET	songs/deleted	?action=deleted_songs
GET	songs/lookup/url-to-song	?action=url_to_song
GET	songs/playlist-generate	?action=playlist_generate
GET	songs/search	?action=search&type=song	advanced_search
GET	songs/stats	?action=stats&type=song
GET	songs	?action=songs
GET	system-preferences/{preference_name}	?action=system_preference&filter={preference_name}
GET	system-preferences	?action=system_preferences
GET	update	?action=system_update
POST	users/{user_id}/commands	?action=toggle_follow&filter={user_id}
POST	users/{user_id}/follow	?action=toggle_follow&filter={user_id}
GET	users/{user_id}/followers	?action=followers&filter={user_id}
GET	users/{user_id}/following	?action=following&filter={user_id}
GET	users/{user_id}/timeline	?action=timeline&filter={user_id}
GET	users/{user_id}	?action=user&filter={user_id}
PATCH	users/{user_id}	?action=user_edit&filter={user_id}
DELETE	users/{user_id}	?action=user_delete&filter={user_id}
GET	users/search	?action=search&type=user	advanced_search
GET	users	?action=users
PUT	users	?action=user_create
PUT	videos/{video_id}/bookmark	?action=bookmark_create&filter={video_id}&type=video
POST	videos/{video_id}/commands	?action={flag|rate|share|player|localplay}&filter={video_id}&type=video
POST	videos/{video_id}/flag	?action=flag&filter={video_id}&type=video
POST	videos/{video_id}/localplay	?action=localplay&command=add&filter={video_id}&type=video
POST	videos/{video_id}/playback	?action=player&filter={video_id}&type=video
POST	videos/{video_id}/rate	?action=rate&filter={video_id}&type=video
POST	videos/{video_id}/share	?action=share&filter={video_id}&type=video
GET	videos/{video_id}	?action=video&filter={video_id}
GET	videos/deleted	?action=deleted_videos
GET	videos/search	?action=search&type=video	advanced_search
GET	videos/stats	?action=stats&type=video
GET	videos	?action=videos

Updated Conversion Examples

RPC API	RESTful API
?action=song&id=123	GET /rest/6/json/songs/123
?action=artist&id=45	GET /rest/6/json/artists/45
?action=album&id=78	GET /rest/6/json/albums/78
?action=artists	GET /rest/6/json/artists
?action=playlist_songs&id=9	GET /rest/6/json/playlists/9/songs
?action=add_song&playlist=9&song=123	POST /rest/6/json/playlists/9/songs

HTTP Method Alignment

The RESTful API uses standard HTTP semantics:

Method	Purpose	Example
GET	Retrieve resource or collection	/rest/6/json/songs/123
POST	Create resource or relationship	/rest/6/json/playlists
PUT	Replace full resource	/rest/6/json/songs/123
PATCH	Partial update	/rest/6/json/songs/123
DELETE	Remove resource	/rest/6/json/playlists/9

State-changing behaviour is no longer implemented via GET.

Resource Naming Conventions

To ensure consistency across the API:

• Use plural nouns for collections
  • songs
  • artists
  • albums
  • playlists
• Use nested routes for relationships
  • artists/{id}/albums
  • albums/{id}/songs
  • playlists/{id}/songs
• Avoid verbs in URLs
• Use HTTP methods to express intent

Versioning Strategy

All RESTful endpoints are prefixed with:

/rest/{version}/{format}

Example

/rest/6/json/songs
/rest/6/xml/artists/45

Versioning enables:

• Backward compatibility
• Parallel support for RPC endpoints
• Incremental evolution of the API
• Clear OpenAPI documentation per version

Authentication and Headers

The RESTful API aligns with OpenAPI specification standards and expects:

• Authentication token passed via headers
• Proper Content-Type and Accept headers
• JSON as the primary response format in documentation
• XML support remains available where specified.

Backwards Compatibility

• RPC endpoints remain functional
• RPC actions are marked as deprecated in REST documentation
• The RPC and REST APIs will coexist

Benefits of RESTful Conversion

Clarity

Endpoints describe the resource being accessed rather than an action being executed.

Predictability

Developers can infer endpoints from resource structure.

Standards Alignment

Fully compatible with OpenAPI tooling and modern REST conventions.

Cache Compatibility

Improved support for HTTP caching layers and reverse proxies.

Tooling Integration

Works seamlessly with:

• OpenAPI generators
• SDK generation tools
• Postman collections
• Automated testing frameworks

Migration Recommendations

1. Identify RPC usage in existing integrations
2. Map each action to its RESTful resource equivalent
3. Replace query-based calls with proper HTTP verbs
4. Update authentication handling to header-based tokens
5. Validate against the OpenAPI schema

Conversion Rules

• RPC endpoints must remain accessible and fully functional
• REST documentation reflects canonical behaviour
• Separate OpenAPI documentation is maintained for REST endpoints
• New features must be implemented using RESTful resource paths only

This RESTful specification establishes a cleaner, scalable, and standards-aligned foundation for the Ampache API.