REST requests are modelled after the way a web browser sends requests to a web server. So, when we use the PHP programming language for REST requests, our PHP scripts mimic the way a web browser interacts with a web server.

PHP, being an extremely flexible and feature-rich language, provides a number of different mechanisms you can choose from to make your REST requests. The ones we recommend are:

The PHP extension cURL is widely used for making Web services requests. It must be loaded in your PHP configuration file, called php.ini. Editing this file normally requires administrative privileges on your server. To see whether cURL is installed and active in your PHP build call the phpinfo function and browse the output.

The following code example taken from util.php makes a request using cURL and stores the response.

// Initialize the cURL session with the request URL$session=curl_init($url);

PHP's file_get_contents function lets you easily fetch a URL and return the contents as a string. Its main drawback is that your PHP installation must have fopen wrappers enabled in order to access URLs. If fopen wrappers is not enabled, you will not be able to use file_get_contents for Web services requests.

The following code example makes a request using file_get_contents and stores the response.

The Decibel REST API returns data in two formats XML and JSON. To make it easier to parse the response the data can be interpreted into manageable objects.

SimpleXML is a PHP extension which provides a very simple and easily usable toolset to convert XML to an object that can be processed with normal property selectors and array iterators.The simplexml_load_string function takes a well-formed XML string and returns it as an object.

The following code example requests albums by artist name, interprets the XML response and outputs the search results.

// Set the character encoding to UTF-8header('Content-Type: text/html; charset=utf-8');

function beginAlbumRetrieve($albumID,$applicationID,$applicationKey){// Set the request URL$depth='Tracks;ImageThumbnail;Media;Names;Publications;Performances;';$url='http://api.decibel.net/v1/Albums/?depth='.$depth.'&id='.$albumID.'&format=xml';

// Issue the request to the Decibel Web Service$response=request($url,$applicationID,$applicationKey);

// Set the character encoding to UTF-8header('Content-Type: text/html; charset=utf-8');

function beginParticipantRetrieve($participantID,$applicationID,$applicationKey){// Set the request URL$depth='Names;GroupMembers;Nationalities;GeographicAreas;Annotations;ChartsAwards;Relationships;';$url='http://api.decibel.net/v1/Participants/?depth='.$depth.'&id='.$participantID.'&format=xml';

// Issue the request to the Decibel Web Service$response=request($url,$applicationID,$applicationKey);

function beginParticipantAssociates($participantID,$applicationID,$applicationKey){// Set the request URL$depth='Names;GroupMembers;Nationalities;GeographicAreas;Annotations;ChartsAwards;Relationships;';$url='http://api.decibel.net/v1/Participants/'.$participantID.'/Associates?depth='.$depth.'&format=xml';

// Issue the request to the Decibel Web Service$response=request($url,$applicationID,$applicationKey);

function beginParticipantTrackAppearances($participantID,$applicationID,$applicationKey){// Set the request URL$depth='Names;GroupMembers;Nationalities;GeographicAreas;Annotations;ChartsAwards;Relationships;';$url='http://api.decibel.net/v1/Participants/'.$participantID.'/Tracks?depth='.$depth.'&format=xml';

// Issue the request to the Decibel Web Service$response=request($url,$applicationID,$applicationKey);

// Set the character encoding to UTF-8header('Content-Type: text/html; charset=utf-8');

function beginTrackRetrieve($trackID,$applicationID,$applicationKey){// Set the request URL$depth='Names;Participations;ExternalIdentifiers;Genres;Performances;';$url='http://api.decibel.net/v1/Tracks/?depth='.$depth.'&id='.$trackID.'&format=xml';

// Issue the request to the Decibel Web Service$response=request($url,$applicationID,$applicationKey);

// Set the character encoding to UTF-8header('Content-Type: text/html; charset=utf-8');

function beginWorkRetrieve($workID,$applicationID,$applicationKey){// Set the request URL$depth='Annotations;ChartsAwards;Genres;Movements;Names;Nationalities;Publications;Publishers;';$url='http://api.decibel.net/v1/Works/?depth='.$depth.'&id='.$workID.'&format=xml';

// Issue the request to the Decibel Web Service$response=request($url,$applicationID,$applicationKey);

function beginWorkTrackAppearances($workID,$applicationID,$applicationKey){// Set the request URL$depth='Annotations;ChartsAwards;Genres;Movements;Names;Nationalities;Publications;Publishers;';$url='http://api.decibel.net/v1/Works/'.$workID.'/Tracks'.'?depth='.$depth.'&format=xml';

// Issue the request to the Decibel Web Service$response=request($url,$applicationID,$applicationKey);

The WebClient class in the System.Net namespace provides methods for receiving data from a resource identified by a URI.

The Rest API is stateless, which means you need to identify yourself with each call.

The WebClient instance does not send optional HTTP headers by default. On each call to the API you will need an Application ID, Application Key and Timestamp included in your HTTP request header. To make this easier a function called SetDecibelRequestHeaders(WebClient, AppID, AppKey) is defined in the Util.cs class.

By default, the Decibel REST API returns results as JSON. You can ask for XML instead by adding the following header to your request

client.Headers.Add("accept", "application/xml");

The DownloadStringAsync(Uri) method downloads a String from a resource, without blocking the calling thread. This enables the application to continue doing useful work while the method call runs.

The DownloadStringCompleted event is raised each time an asynchronous operation to download a resource as a string completes. The DownloadStringCompletedEventArgs class provides the event handler with event data.

The following code example requests albums by artist name and stores the XML response.

The Decibel REST API returns data in two formats XML and JSON. To make it easier to parse the response the data can be deserialized into manageable objects.

To deserialize the Decibel REST API responses you will need to add the Decibel Object Model file to your project. This file contains the class definitions for the different types of objects which can be requested from the API.

The XmlSerializer class in the System.Xml.Serialization namespace enables you to deserialize XML documents into objects of a specified type.
It should be constructed with the type of the object that will be deserialized. The typeof operator is used to obtain the System.Type object for a type.

The following code example deserializes the XML response from a Albums API call to a AlbumQueryResult object.