railroad / soundslice
Communicate with Soundslice API
Installs: 5 421
Dependents: 0
Suggesters: 0
Security: 0
Stars: 0
Watchers: 2
Forks: 0
Open Issues: 0
Requires
- php: >=7.1.3
- guzzlehttp/guzzle: ~6.0
- laravel/framework: 5.6.*
Requires (Dev)
- orchestra/database: ~3.6
- orchestra/testbench: ~3.5
- phpunit/php-code-coverage: ~6.0
- phpunit/phpunit: ~7.0
README
Endpoints and service for connecting your application to Soundslice via their API.
Soundslice API docs: https://www.soundslice.com/help/data-api/
Installation
Install
Register Service Provider
Add the SoundsliceServiceProvider to your application's list of service-providers ("providers" property, array) in /config/app.php.
Publish Config
Run this command to publish the package's config file(s) to your application's config directory:
$ php artisan vendor:publish
Provide Soundslice Credentials
Provide the following environmental variables:
SOUNDSLICE_APP_ID
SOUNDSLICE_SECRET
See Lastpass Secure Note "Musora - Local .env" (in "Shared Railroad Web Development" -> "Local Dev" -> )
(For acceptance tests, copy .env.testing.example and rename it ".env.testing", and provide the respective environmental variables there. It's already added to .gitignore)
API Reference
Notes
endpoints
Prepend all endpoints below with /soundslice/
.
Anything in curly braces is an inline parameter.
For example if below it says get/{slug}
, then your endpoint for the
slug foo
would actually be /soundslice/get/foo
.
Defaults
All optional booleans default to false
unless noted otherwise.
List of methods available
- createScore
- list
- get
- delete
- move
- folder create
- folder delete
- create notation
Errors
All errors are available as an item in the Json response's errors
array (which exists in place of the data
array).
Example:
{ "errors":[ { "status":"Internal Server Error", "code":500, "title":"SoundSliceJsonController@createScore failed", "detail":"flux capacitor exceeded threshold with gamma output of 28937u4893 hertz." } ] }
This is as per my attempts to understand the json-api docs.
Each error item will have the fields as per the example below:
status:
the HTTP status code applicable to this problem, expressed as a string value.
code:
an application-specific error code, expressed as a string value.
title:
a short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization.
detail:
a human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized
Validation Errors
Details
Will return 400 Bad Request
with an "error" object as the data. The detail
item in that error with have information
about why the validation failed.
There is an item for each field that failed, and each field item will contain an item for each failure reason.
For example, say we were trying to create a new "baz". If the "foo" field failed because it was non-numeric and longer than 16 characters we'll see something like this:
{ "errors":[ { "status":"Bad Request", "code":400, "title":"create baz request validation failure", "detail":{ "foo":[ "The foo must be a number." ] } } ] }
If there was that failure - two validation failures on just one field, and then validation failure on a whole other field, it would look like this: (let's say the "artist" field is manditory)
{ "errors":[ { "status":"Bad Request", "code":400, "title":"create baz request validation failure", "detail":{ "foo":[ "The foo may not be greater than 16.", "The foo must be a number." ], "bar":[ "The bar field is required." ] } } ] }
Detail sub-values are a human-friendly reason for failure.
Methods
create score
PUT "create"
* For notes about these params see the "Create Score Parameter Notes" section below
Returns, on success
- status code
201
- status text
Created
slug
string
{ "statusText":"Created", "status":201, "data":{ "slug": "fo1337br" } }
list scores
GET "list"
Returns, on success
- status code
200
- status text
OK
scores
array with all the scores for the account.
Example (account in for this example only has two scores):
{ "statusText":"OK", "status":200, "data":{ "scores":[ { "status":1, "show_notation":true, "print_status":1, "can_print":false, "embed_status":1, "name":"nameFoo ex", "artist":"artistFoo pariatur ab", "slug":"fo154364br", "recording_count":0, "has_notation":false } ] } }
get score
GET "get/{slug}"
Returns, on success
- status code
200
- status text
OK
score
array
{ "statusText":"OK", "status":200, "data":{ "score": { "status":1, "show_notation":true, "print_status":1, "can_print":false, "embed_status":1, "name":"nameFoo labore natus", "artist":"artistFoo atque repellendus iusto", "url":"/scores/154453/", "recording_count":0, "has_notation":false } } }
delete score
DELETE "delete"
Returns, on success
- status code
200
- status text
OK
deleted
integer representing a boolean value
{ "statusText":"OK", "status":200, "data":{ "deleted": 1 } }
move score
UNDER CONSTRUCTION
POST "move"
Returns, on success
folder create
PUT "folder/create"
Returns, on success
- status code
201
- status text
Created
folder-id
string
{ "statusText":"Created", "status":201, "data":{ "folder-id": "fo1337br" } }
folder delete
DELETE "folder/delete"
Returns, on success
- status code
200
- status text
Created
delete
integer representing a boolean value
{ "statusText":"OK", "status":200, "data":{ "deleted": 1 } }
create notation
PUT "notation"
asset-url
should be a publicly-accessible URL that provides the relevant media file (ex: musicxml file)
Returns, on success
- status code
200
(BECAUSE DOES NOT CREATE) - status text
OK
(BECAUSE DOES NOT CREATE) notation
integer representing boolean value. DOES NOT REPRESENT CREATION OF NOTATION, ONLY SUCCESS IN STARTING PROCESS THAT ATTEMPTS CREATION - YOU MUST REQUEST GET TO DETERMINE SUCCESS.
{ "statusText":"OK", "status":200, "data":{ "notation": 1 } }
Create Score Parameter Notes
"publicly-listed"
Specifies who can view the score on soundslice.com. (Embeds ignore this and use embed_status.)
false
- “Only me”
true
- “Anybody who knows its URL”
Embed options
Reference: Soundslice's embedding docs.
"embed-white-list-only"
false
- Not restricted only to whitelist domains - defers to embed-globally
option
true
- Allowed only on whitelist domains
"embed-globally"
false
- Disabled (default value, if not provided)
true
- Allowed on any domain
A note about the embed-white-list-only and embed-globally options
These are options of this soundslice-integrating package that abstract options of the actual Soundslice API.
Thus, if you look directly at the Soundslice API you'll see this instead:
embed_status Optional
An integer specifying embed options. For more, see embedding docs.
1 — Disabled (default value, if not provided)
2 — Allowed on any domain
4 — Allowed on whitelist domains
This package determines which integer to specify for the that (embed_status
) option the following way:
$embedWhiteListOnly ? 4 : ($embedGlobally ? 2 : 1)
Just an FYI lest you look at soundslice's API docs when attempting to use this method of this integration package.
These are our test-cases
(in soundslice/tests/Acceptance/SoundsliceTest.php)
- create_score
- create_score_fails_folder_id_not_whole_number
- create_score_fails_folder_does_not_exist
- create_score_fails_already_exists
- create_score_validation_fail
- list
- get_score
- get_score_not_found
- delete_score
- delete_score_not_found
- delete_score_validation_failure
- create_folder
- create_nested_folder
- create_folder_validation_failure
- create_folder_failure_invalid_parent_id
- delete_folder
- delete_folder_not_found
- delete_folder_validation_failure
- create_notation
- create_notation_validation_failure
- create_notation_upload_more_than_one
- create_notation_with_same_values