RPG Musik-Tags Datenbasis

API

This page describes the API of the web service for developers. The main services are for up- and download of data. Further services are to browse the database.

All services are also described technically in the metadata page.

This page is only available in English.

General Notes

The services are implemented with ServiceStack.net. If you have problems accessing them, the documentation and help of ServiceStack should be the first place to look for solutions. See also the ServiceStack clients documentation page.

Parameters for the services can be given and returned in several formats, most importantly JSON, XML and JSV. Important: parameters of complex datatypes must be serialized in the JSV format for upload, and will be serialized in the JSV format for download.

Download

With this service, you can retrieve tags for files.

Name Type Required Description
FileIdentification List<FileIdentification>YesIdentifies the files. Custom data type serialized with JSV.
Test boolean No Set to true to access a test database instead of the normal database
Name Type Description
Status int Error code: 0 on success, 1 on failure
ErrorMessage String Describes the error on failure
TagsData TagsExportedDataRetrieved tags. Custom data type serialized with JSV.
NrOfFoundFilesint The number of files in the request which were found in the database.

Upload

With this service, you can add tags for files to the database. It is strongly recommended that you test your client well with the test database (setting the parameter Test to true on each request) before using the normal database.

Name Type Required Description
TagsData TagsExportedDataYesData to put into the database. Custom data type serialized with JSV.
User String YesUser Id. Ares uses a hash over a mail address, but it can be any string.
IncludeLogboolean No If set to true, the response will include a log about the import operation.
Test boolean No Set to true to access a test database instead of the normal database
Name Type Description
Status int Error code: 0 on success, 1 on failure
ErrorMessage StringDescribes the error on failure
Log StringLog about the import operation, if it was requested

Browse

There are multiple services which are used to browse the database. They can all be accessed with any request type (though GET should be used normally), and they share some common parameters:

Name Type Required Description
LanguageCodeStringNo A two-letter ISO 639-1 language code (e.g. "de"). The database is browsed regarding tags and categories in that language.
WebLanguage StringNo Either "de" or "en": determines whether web pages shown as response are in German or in English.
Test boolean No Set to true to access a test database instead of the normal database

These three parameters are also always included in the response for a browse request; the first two wrapped inside a LanguageResponse.

In particular, the following browsing services are available:

Path Description
/ArtistsReturns all artists
/Artists/{Name}Returns all albums by an artist
/AlbumsReturns all albums
/Albums/{Name}Returns all titles in an album
/Artists/{Artist}/{Album}Returns all titles in an album
/FilesReturns all titles
/CategoriesReturns all categories
/Categories/{Name}Returns all tags in a category
/Tags/{Name}Returns all titles with a tag
/Tags/{Category}/{Name}Returns all titles with a tag
/Files/{Id}Returns all tags of a title
/StatisticsReturns statistics about the database

The parameters of the responses should be pretty self-explanatory. Services which return several items always return them in a list parameter called Results.

Custom Data Types

For the Upload and Download services, custom data types are used to identify the files and to wrap the actual data. The data types are given as their C# class definitions with their descriptive comments here:

            
    /// <summary>
    /// Identifies a file / title in the database.
    /// </summary>
    public class FileIdentification
    {
        /// <summary>
        /// Id of the file. Used for cross-referal in TagsExported data.
        /// </summary>
        public int Id { get; set; }
        /// <summary>
        /// Artist of the title. Only used for identification if no
        /// Acoust Id is given.
        /// </summary>
        public String Artist { get; set; }
        /// <summary>
        /// Album of the title. Only used for identification if no
        /// Acoust Id is given.
        /// </summary>
        public String Album { get; set; }
        /// <summary>
        /// Title name. Only used for identification if no 
        /// Acoust Id is given.
        /// </summary>
        public String Title { get; set; }
        /// <summary>
        /// Identifies the music title globally. See 
        /// <a href="http://acoustid.org/">AcoustId</a> for more information.
        /// </summary>
        public String AcoustId { get; set; }
    }

    /// <summary>
    /// A translation of an item into a language.
    /// </summary>
    public class TranslationExchange
    {
        /// <summary>
        /// Id of the language.
        /// </summary>
        public long LanguageId { get; set; }
        /// <summary>
        /// Name of the item in that language.
        /// </summary>
        public String Name { get; set; }
    }

    /// <summary>
    /// Information about a language.
    /// </summary>
    public class LanguageExchange
    {
        /// <summary>
        /// Two-letter ISO-6391 code which identifies the languages.
        /// </summary>
        public String ISO6391Code { get; set; }
        /// <summary>
        /// Id of the language for referencing it e.g. in an TranslationExchange.
        /// </summary>
        public long Id { get; set; }
        /// <summary>
        /// Names of the language (in possibly several languages).
        /// </summary>
        public List<TranslationExchange> Names { get; set; }
    }

    /// <summary>
    /// Information about a category.
    /// </summary>
    public class CategoryExchange
    {
        /// <summary>
        /// Id of the category for referencing it e.g. in a TagExchange.
        /// </summary>
        public long Id { get; set; }
        /// <summary>
        /// Names of the category (in possibly several languages).
        /// </summary>
        public List<TranslationExchange> Names { get; set; }
    }

    /// <summary>
    /// Information about a tag.
    /// </summary>
    public class TagExchange
    {
        /// <summary>
        /// Id of the tag for referencing it e.g. in a TagsForFileExchange.
        /// </summary>
        public long Id { get; set; }
        /// <summary>
        /// Category of the tag.
        /// </summary>
        public long CategoryId { get; set; }
        /// <summary>
        /// Names of the tag (in possibly several languages).
        /// </summary>
        public List<TranslationExchange> Names { get; set; }
    }

    /// <summary>
    /// Information about an assignment of tags to a file.
    /// </summary>
    public class TagsForFileExchange
    {
        /// <summary>
        /// Id of the file.
        /// </summary>
        public long FileId { get; set; }
        /// <summary>
        /// Ids of the assigned tags.
        /// </summary>
        public List<long> TagIds { get; set; }
    }

    /// <summary>
    /// Wrapper around exchanged data.
    /// </summary>
    public class TagsExportedData
    {
        /// <summary>
        /// Languages in the data.
        /// </summary>
        public List<LanguageExchange> Languages { get; set; }
        /// <summary>
        /// Categories in the data.
        /// </summary>
        public List<CategoryExchange> Categories { get; set; }
        /// <summary>
        /// Tags in the data.
        /// </summary>
        public List<TagExchange> Tags { get; set; }
        /// <summary>
        /// Files (music titles) in the data.
        /// </summary>
        public List<FileIdentification> Files { get; set; }
        /// <summary>
        /// Tags which are assigned to the files.
        /// </summary>
        public List<TagsForFileExchange> TagsForFiles { get; set; }
        /// <summary>
        /// Tags which have been removed from the files ("downvoting").
        /// </summary>
        public List<TagsForFileExchange> RemovedTags { get; set; }
    }