Report created: 19 June 2014

Participant Information

Experience: 7 years total: 6 years - ASP.NET, 1 year - Ruby/Ruby on Rails

Development System: Microsoft Windows 7 x64; JetBrains RubyMine 6.0.3; Ruby 2.0

 

Tasks

1. Create a simple application that returns list of tracks for an account.

For all tasks use the following accounts:

SoundCloud account:
    Login: test73837
    Password: fe_ff_f22ff

Gmail Account:
    Login: test73837@gmail.com
    Password: vs_dv22_3r

If you need sample tracks use the following samples:

https://drive.google.com/file/d/0ByJFNf4ZBEb5dWJtXy05SmdzZVk/edit?usp=sharing

Sources: download

Time spent: 1 hour 10 minutes

Notes:

When I opened https://developers.soundcloud.com/ I was confused by many available options:

For example, what is the difference between "Soundcloud SDK" and "HTTP API Wrappers"? I hadn't used the API before so it wasn't clear for me which option to choose.

I clicked "Soundcloud SDK" and I was redirected to the "HTTP API Wrappers" page. Then I clicked "Ruby" on the right and I was redirected to Ruby SDK github page.

I installed the ruby gem successfully and decided to run the first example on the github page, but first I had to replace YOUR_CLIENT_ID with my client id. I didn't have any idea what client id is and where I can get it.

By the way, the example's comment "# register a client with YOUR_CLIENT_ID as client_id_" is useless.

I started guessing. I signed into my account and clicked "Developers":

It redirected me to the Soundlcoud API documentation page.

Ok, let's try to find something like "ClientId" in my settings... dashboard... username&profile link:

Ok, maybe the client id is my username?

I tried that and I got the following error (I took the example from the github page):

Well, there is an error in the example, they forgot to add

require 'soundcloud'

to the example.

I added the line, run the example and got the following error:

So, it seems client id is not my username.

I moved from the github page documentation to Soundcloud API documentation, started read HTTP API Guide from start to finish and accidentally noticed under “Authentication” section the following lines: This section presumes you have: 1. “Registered your App”. Then I clicked "Registered your App" and it redirected me to http://soundcloud.com/you/apps so I need to input some information about my app. Actually it is not clear what I should enter for "redirect uri" if I am just creating small local application. I left it empty and finally saw Client ID field.

Well, I think it should be more information on what Client ID is on the github page. I typed the id into my example and it worked.

Actually, it is not clear what the reason is to have TWO documentations. I mean one on the github page (https://github.com/soundcloud/soundcloud-ruby) and the second one on the soundcloud API documenation page (http://developers.soundcloud.com/docs/api/guide). Also, they seem unsynchronized.

So it seems I should use API Guide documentation, not the github one.

I looked through API Guide and API Reference and I finally managed to get that I should use "me/tracks" + username/password authentication.

When I was trying to do the task, I tried to query '/tracks/test73837'. It returned just simple HTTP 404. If it returned something like “No such track error”, it'd be much easier.

2. Upload the track sample1.mp3 to the account.

Sources: download

Time spent: 10 minutes

Notes:

I managed to complete the task fast because there is an example for that.

3. Add an ability to get the track sample1.mp3 by your application.

Sources: download

Time spent: 45 minutes

Notes:

I took the example from the documentation (the "Streaming Sounds" section: http://developers.soundcloud.com/docs/api/guide#playing):

require 'soundcloud'

# create a client object with your app credentials
client = Soundcloud.new(:client_id => '5037f01cf665118f39ae4757b0984f1b',
                        :client_secret => 'c642235e1d3666ac0580706e46c42d91',
                        :username => 'test73837',
                        :password => 'fefff22ff')

# fetch track to stream
track = client.get('/tracks/149946199')

# get the tracks streaming URL
stream_url = client.get(track.stream_url, :allow_redirects => true)

# print the tracks stream URL
puts stream_url.location

but it doesn't work:

Well, I think it's a bug in Ruby SDK.

One more note: I think it would be useful to mark the operations that can be completed with/without authentication in the API Reference, because when I looking through the reference I can't get if I need to be authenticated or not for some operations.

4. Update a description of the track sample1.mp3.

Sources: download

Time spent: 10 minutes

Notes:

It was easy, there is an example for that.

5. Implement search by word "classic" and print list of the search results.

Sources: download

Time spent: 5 minutes

Notes:

There is an example for that too.

Questions

1. Name at least three of the most difficult problems you encountered during task execution and how you solved them (documentation, forums, stackoverflow, help from a friend, ...).

  1. Find out a single entry point in the documentation.
  2. Understand what my client id is. I accidentally found out what it is when I registered my test application on Soundcloud.
  3. Find out that
    client.get(track.stream_url, :allow_redirects => true)
    
    returns binary data and not an url. I figured it out by experiments.

2. Have you experienced any unexpected errors? If yes, did you find the error messages useful?

Yes, I experienced some errors due my faults; but in the 3rd example I experienced location method error and I didn’t managed to fix it. Well, I think HTTP 404 errors should contain more information about an actual errors.

3. Did you find that some classes or methods behave non-obviously or unexpectedly?

Yes,

client.get(track.stream_url, :allow_redirects => true)
returns binary data and not an url.

4. Name at least three ways we can improve the documentation.

  1. Make clear and simple entry points for the documentation.
  2. Remove documentation duplication (documentation on the github page https://github.com/soundcloud/soundcloud-ruby and documentation on http://developers.soundcloud.com/)
  3. Check that examples work.
  4. I think it would be useful to mark the operations that could be completed with/without authentication in the API Reference.
  5. I really would like to have more information on Ruby SDK objects, methods, method parameters, return values.

5. Name at least three ways we can improve design of the API.

It is difficult to say. It seems everything is pretty straightforward and Soundcloud developers do the great service. However I have some minor notes:
    1. When I was trying to do task1, I tried to query '/tracks/test73837'. It returned HTTP 404. If it returned something like “No such track error”, it'd be much easier.
    2. Right after I upload a track to the service, the track is unavailable for some time since it is being processed by Soundcloud. So, for example, if I would like to update the description of the track I just get: HTTP "404 Not Found " error. Well, it took some time to undestand what it the reason of the error. It would be much more easier if I get something like "the track is being processing" or something like that... But of course it is not an important issue.
    3. Probably you should consider making a Ruby SDK more object-oriented. I mean for now it looks like a helper library to make requests to the service (and it is really useful), but probably it would be better if we have some object oriented version of the SDK, something like that:

client#tracks
client#upload_track(track)

track#id
track#title='title1'

 

www.apiusabilitytesting.com