Currently, OneMusicAPI only has a REST-style HTTP interface. We're now releasing an SDK for PHP which makes performing OneMusicAPI queries and lookups much easier.

How is it easier? Well, before we just exposed a HTTP interface, to which you could send query parameters and the like and receive JSON or images in response. Using the SDK you don't need to know worry about anything at the HTTP level and can just concentrate on using the service in your language of choice.

How do I use it?

Let's start with installation.

The easiest way of getting started is to fork our example project, example-php, and make changes from there.

$ git clone https://github.com/OneMusicAPI/example-php.git
Cloning into 'example-php'...
[...]

Inside example-php you'll find:

composer.json
Specification of the dependencies. Pay particular attention to the client-php dependency.
composer.lock
Generated dependency information. Yes, this is intended to be committed to source control.
index.php
The source code you can copy.
README.md
Instructions about setting up the example.

Now, let's review the code. All the important stuff is in index.php. Cast your eyes down to the <?php statement.

After our require_once statement, which auto loads the API, we can write some code to make queries to OneMusicAPI. First, instantiate the API class:

$apiInstance = new OneMusicAPI\Client\Api\ReleaseApi(
    // If you want use custom http client, pass your client which implements `GuzzleHttp\ClientInterface`.
    // This is optional, `GuzzleHttp\Client` will be used as default.
    new GuzzleHttp\Client()
    //$config
);

We now configure the query:

$user_key='';
$title = 'Screamadelica'; // string | 
$artist = 'Primal Scream'; // string | 
//$barcode = ''; // string | 
$must_inc='images';
$max_result_count = 5; // int | 
$min_certainty = 0.7; // float | 
//$min_image_score = 0; // int | 
//$min_image_width = 0; // int | 
//$min_image_height = 0; // int | 
//$max_image_width = 99999; // int | 
//$max_image_height = 99999; // int | 

Remember to set your user_key! Finally, make the query, which returns some results:

try {
    $result = $apiInstance->release($user_key, $inc, $must_inc, $max_result_count, $min_certainty, $min_image_score, $min_image_width, $min_image_height, $max_image_width, $max_image_height, $title, $artist, $barcode);
} catch (Exception $e) {
    echo 'Exception when calling ReleaseApi->release: ', $e->getMessage(), PHP_EOL;
}

We can now use the results in our HTML:

How does it work?

We've begun the reverse-specification of our API using OpenAPI. This is a standard approach to describing how APIs work; their operations, data models etc. Using this specification, we can use tools like OpenAPI Generator to generate SDKs.

Want more?

Want an SDK in a different language? Let us know - our use of OpenAPI means it should be easy to generate a new SDK for most mainstream languages.

comments powered by Disqus
© 2012-2020 elsten software limited, Unit 4934, PO Box 6945, London, W1A 6US, UK | terms and conditions | privacy policy