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.
- Request type: must be POST
- Path: /Download
- Parameters:
Name | Type | Required | Description |
---|---|---|---|
FileIdentification | List<FileIdentification> | Yes | Identifies the files. Custom data type serialized with JSV. |
Test | boolean | No | Set to true to access a test database instead of the normal database |
- Response:
Name | Type | Description |
---|---|---|
Status | int | Error code: 0 on success, 1 on failure |
ErrorMessage | String | Describes the error on failure |
TagsData | TagsExportedData | Retrieved tags. Custom data type serialized with JSV. |
NrOfFoundFiles | int | 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.
- Request type: must be POST
- Path: /Upload
- Parameters:
Name | Type | Required | Description |
---|---|---|---|
TagsData | TagsExportedData | Yes | Data to put into the database. Custom data type serialized with JSV. |
User | String | Yes | User Id. Ares uses a hash over a mail address, but it can be any string. |
IncludeLog | boolean | 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 |
- Response:
Name | Type | Description |
---|---|---|
Status | int | Error code: 0 on success, 1 on failure |
ErrorMessage | String | Describes the error on failure |
Log | String | Log 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 |
---|---|---|---|
LanguageCode | String | No | A two-letter ISO 639-1 language code (e.g. "de"). The database is browsed regarding tags and categories in that language. |
WebLanguage | String | No | 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 |
---|---|
/Artists | Returns all artists |
/Artists/{Name} | Returns all albums by an artist |
/Albums | Returns all albums |
/Albums/{Name} | Returns all titles in an album |
/Artists/{Artist}/{Album} | Returns all titles in an album |
/Files | Returns all titles |
/Categories | Returns 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 |
/Statistics | Returns 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; }
}