- Previous: Request Format
- Up: Introduction
- Next: Result Codes
Response Elements
This page explores common response elements. Please see individual API
method documentation for method-specific response details.
RESPONSE
The response of every eMusic API method is wrapped in a </response> element. The response element contains a status (e.g., "success" or "failure"), zero or more messages and an "options" element. This is followed by the method-specific response elements. The response element is explicit for the XML format (root document node: <response>) and implied for the JSON / JSONP formats. A response has the following properties:
STATUS
Every response element contains a result status. Though the status codes mimic HTTP protocol codes, they are returned as part of the response XML (and JSON / JSON) and are in addition to the actual server response code.
For a complete list of status names and values, please see the result codes page. A status has the following properties:
MESSAGES
The <message> element is a <list> element that contains one or more messages. Messages are typically used to help interpret exceptional status codes and, as such, are not present for normal responses. Each message has the following properties:
OPTIONS
The options element lists the non-default option settings for each method invocation. This is a "sanity-check" response mechanism for developers, supplying developers with the options they specified with the request. For more information about potential values for each request option, see Request Parameters. There are four properties that are available to almost all methods:
SEARCH
A search element is returned for all search methods and contains the search term.
VIEW
A view element is returned for all search and browse methods. It contains a summary of the paginated result counts, including information about the returned result set.
BROWSE
A browse element is returned for methods that incorporates filtering and sorting.
RESPONSE
The response of every eMusic API method is wrapped in a </response> element. The response element contains a status (e.g., "success" or "failure"), zero or more messages and an "options" element. This is followed by the method-specific response elements. The response element is explicit for the XML format (root document node: <response>) and implied for the JSON / JSONP formats. A response has the following properties:
| Name | Type | Description |
| status | (see below) | The status contains a result code. (See result codes.) |
| messages | (see below) | Messages contains one or more messages. Optional. |
| options | (see below) | Contains a list of method options (e.g., response format, image size, etc.). |
| search | (see below) | Returned for search methods only. Contains the search term. |
| view | (see below) | Returned for search and browse methods only. Contains a summary of paginated result counts (e.g., number of pages, results per page, etc.). |
| browse | (see below) | Returned for methods that contains filtering and sorting. |
STATUS
Every response element contains a result status. Though the status codes mimic HTTP protocol codes, they are returned as part of the response XML (and JSON / JSON) and are in addition to the actual server response code.
For a complete list of status names and values, please see the result codes page. A status has the following properties:
| Name | Type | Description |
| code | integer | A numerical status code that relates loosely to HTTP result codes. |
| name | string | A string representation of the numerical code. |
MESSAGES
The <message> element is a <list> element that contains one or more messages. Messages are typically used to help interpret exceptional status codes and, as such, are not present for normal responses. Each message has the following properties:
| Name | Type | Description |
| code | integer | A proprietary numerical status code. |
| name | string | A string message relating to the status code. |
OPTIONS
The options element lists the non-default option settings for each method invocation. This is a "sanity-check" response mechanism for developers, supplying developers with the options they specified with the request. For more information about potential values for each request option, see Request Parameters. There are four properties that are available to almost all methods:
| Name | Type | Description |
| format | format | The response format supplied in the request. |
| callback | string | The JSONP callback method supplied in the request. |
| fref | string | The FREF value supplied in the request. |
| imageSize | imageSize | The image size supplied in the request. |
SEARCH
A search element is returned for all search methods and contains the search term.
| Name | Type | Description |
| term | searchTerm | The URL-decoded search term. |
VIEW
A view element is returned for all search and browse methods. It contains a summary of the paginated result counts, including information about the returned result set.
| Name | Type | Description |
| page | integer | The page index of the returned result set. Can be specified in the request. The default value is 1. |
| perPage | integer | The number of results returned per page. Can be specified in the request. The default value is 20. |
| pages | integer | The total number of pages. |
| total | integer | The total number of results. |
BROWSE
A browse element is returned for methods that incorporates filtering and sorting.
| Name | Type | Description |
| country | country code | The country filter used to generate the results. |
| filter | string | The primary filter (e.g. downloadedThisMonth). The default value is method-specific. |
| primarySort | string | The primary sort field (e.g. artistDownloadsMonth). The default value is method-specific. |
| primaryAscending | boolean | "true" if the primary sort is sorted upwards. "false" if the primary sort is sorted downwards. The default value is "false". |
| secondarySort | string | The secondary sort field. The default value is method-specific. |
| secondaryAscending | boolean | "true" if the secondary sort is sorted upwards. "false" if the secondary sort is sorted downwards. The default value is "false". |
| type | string | The type of elements returned (e.g. artist, album, label), though this should also be evident by the method name. |
- Previous: Request Format
- Up: Introduction
- Next: Result Codes
Docs Navigation
- Introduction
- Request Format
- Response Elements
- Result Codes
- Response Format
- Code Samples
- Branding Guidelines
- Method Index
- Request Parameters
- Method: Album Charts
- Method: Album Editorial
- Method: Album Info
- Method: Album Picks
- Method: Album Ratings
- Method: Album Reviews
- Method: Album Search
- Method: Artist Charts
- Method: Artist Editorial
- Method: Artist Info
- Method: Artist Picks
- Method: Artist Ratings
- Method: Artist Related
- Method: Artist Search
- Method: Book Charts
- Method: Book Editorial
- Method: Book Info
- Method: Book Ratings
- Method: Book Reviews
- Method: Book Search
- Method: Label Info
- Method: Label Search
- Method: Track Charts
- Method: Track Search
0 Comments
Please sign in to post a comment.