OAuth2 SoundCloud API wrapper written in Java (javadoc).
It is simple to use and requires a minimum of external dependencies (compared to the OAuth1 wrapper) so should be easily embeddable in both desktop and mobile applications.
The wrapper works well on Android (although it has no dependencies on it) since it is an extraction from our SoundCloud Android codebase. However, if all you want is to share sounds from your own application we recommend to check out the Android Sharing Kit which delegates all the hard work to the SoundCloud app and makes use of Android's intent framework.
Create a wrapper instance:
ApiWrapper wrapper = new ApiWrapper("client_id", "client_secret", null, null);Obtain a token:
wrapper.login("username", "password");Execute a request:
HttpResponse resp = wrapper.get(Request.to("/me"));Update a resource:
HttpResponse resp =
wrapper.put(Request.to("/me")
.with("user[full_name]", "Che Flute",
"user[website]", "http://cheflute.com")
.withFile("user[avatar_data]", new File("flute.jpg")));If your app uses OAuth1 and already has users with access tokens you can easily migrate to OAuth2 without requiring anybody to reauthenticate:
Token token = wrapper.exchangeOAuth1Token("validoauth1token");Note that this is specific to SoundCloud and not part of the current OAuth2 draft.
OAuth2 access tokens are only valid for a certain amount of time (usually 1h) and need to be refreshed when they become stale. The wrapper automatically refreshes the token and retries the request so an API client usually does not need to care about this fact. If the client is interested (possibly to persist the updated token) it can register a listener with the wrapper.
Expiring access tokens provide more security but also add more complexity to the authentication process. If you don't want to use them you can request non-expiring tokens by specifying the scope "non-expiring" when exchanging the tokens:
Token token = wrapper.login("username", "password", Token.SCOPE_NON_EXPIRING);The resulting token will be valid until revoked manually.
For the authorization_code grant type you need to request the scope like so:
URI uri = wrapper.authorizationCodeUrl(Endpoints.CONNECT, Token.SCOPE_NON_EXPIRING);
// open uri in browser / WebView etc.Please see FacebookConnect for an example of this login flow.
The wrapper depends on Apache HttpClient (including the HttpMime module) and json-java. The Android SDK already comes with these two libraries so you don't need to include them when using the wrapper there.
The project uses the groovy-based build system gradle (version 1.x):
$ brew update && brew install gradle (OSX+homebrew, check website for other OS)
$ git clone git://github.com/soundcloud/java-api-wrapper.git
$ cd java-api-wrapper
$ gradle jar # build jar file (build/libs/java-api-wrapper-1.x.x.jar)
$ gradle test # run tests
You don't have to use gradle - the repo also contains a pom.xml file which
can be used to build and test the project with Apache Maven (mvn install).
Jar files are available in the Github download section and on sonatype.org / maven (snapshots, releases, maven-central).
The wrapper ships with a few examples in src/examples/java:
- CreateWrapper creates a wrapper and obtains an access token using login / password.
- GetResource performs a GET request for a resource and prints the JSON result.
- PostResource performs a POST request to create a resource and prints the JSON result
- PutResource performs a PUT request to update a resource and prints the JSON result
- UploadFile uploads a file to SoundCloud.
- FacebookConnect obtain an access token via Facebook login
You can use gradle tasks to compile and run these examples with one command. If you don't want to use gradle there is also a precompiled jar with all dependencies available (jar-all).
First create a wrapper and remember to substitute all credentials with real ones (register an app if you need client_id/secret):
# with gradle
$ gradle createWrapper -Pclient_id=my_client_id \
-Pclient_secret=mys3cr3t \
-Plogin=api-testing \
-Ppassword=testing
# with plain java
$ java -classpath java-api-wrapper-1.x.y-all.jar \
com.soundcloud.api.examples.CreateWrapper \
my_client_id mys3cr3t api-testing testing
Output:
got token from server: Token{
access='0000000KNYbSTHKNZC2tq7Epkgxvgmhu',
refresh='0000000jd4YCL0vCuKf6UtPsS6Ahd0wc', scope='null',
expires=Mon May 02 17:35:15 CEST 2011}
wrapper serialised to wrapper.ser
With the wrapper and all tokens serialised to wrapper.ser you can run the
other examples.
GET a resource:
$ gradle getResource -Presource=/me
(java -classpath java-api-wrapper-1.x.y-all.jar \
com.soundcloud.api.examples.GetResource /me)
Output:
GET /me
{
"username": "testing",
"city": "Berlin"
...
}
PUT a resource:
$ gradle putResource -Presource=/me -Pcontent='{ "user": { "city": "Testor" } }' -PcontentType=application/json
Output:
PUT /me
{
"username": "testing",
"city": "Testor"
...
}
POST a resource:
$ gradle postResource -Presource=/playlists -Pcontent='{ "playlist": { "title": "Test" } }' -PcontentType=application/json
Output:
POST /playlists
{
"title": "Test",
"artwork_url": null,
...
}
Upload a file:
$ gradle uploadFile \
-Pfile=src/test/resources/com/soundcloud/api/hello.aiff
(java -classpath java-api-wrapper-1.x.y-all.jar \
com.soundcloud.api.examples.UploadFile ...)
Output:
Uploading src/test/resources/com/soundcloud/api/hello.aiff
.............................................
201 Created https://api.sandbox-soundcloud.com/tracks/2100052
{
"artwork_url": null,
...
}
You can add the debug flag (-d) to gradle to get some extra HTTP logging:
$ gradle getResource -Presource=/me -d
[DEBUG] DefaultClientConnection - Sending request: GET /me HTTP/1.1
[DEBUG] headers - >> GET /me HTTP/1.1
[DEBUG] headers - >> Authorization: OAuth 0000000ni3Br147FO7Cj5XotAy
...
Note that while the example code uses standard Java serialization to persist state across calls you should probably use a different mechanism in your app.
- Fork the project.
- Make your feature addition or bug fix.
- Add tests for it.
- Commit, do not mess with buildfile, version, or history.
- Send a pull request. Bonus points for topic branches.
If you want to work on the code in an IDE instead of a text editor you can easily create project files with gradle:
$ gradle idea # Intellij IDEA
$ gradle eclipse # Eclipse
The API is based on urbanstew's soundcloudapi-java project.
Includes portions of code (c) 2010 Xtreme Labs and Pivotal Labs and (c) 2009 urbanSTEW.
See LICENSE for details.
