disconnect

A full-featured Discogs API v2.0 client library

Downloads in past

Stats

StarsIssuesVersionUpdatedCreatedSize
disconnect
440181.2.23 years ago10 years agoMinified + gzip package size for disconnect in KB

Readme

About

disconnect is a Node.js client library that connects with the Discogs.com API v2.0. Dependency Status

Features

Covers all API endpoints Supports pagination, rate limiting, etc. All database, marketplace and user functions implement a standard function(err, data, rateLimit) format for the callback or return a
native JS [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) when no callback is provided
Easy access to protected endpoints with Discogs Auth Includes OAuth 1.0a tools. Just plug in your consumer key and secret and do the OAuth dance API functions grouped in their own namespace for easy access and isolation

Todo

Add more tests

Installation

NPM

Structure

The global structure of disconnect looks as follows: ``` require('disconnect') -> new Client() -> oauth()
-> database()
-> marketplace()
-> user() -> collection()
-> wantlist()
-> list()
-> util
```

Usage

Quick start

Here are some basic usage examples that connect with the public API. Error handling has been left out for demonstrational purposes.

Init

```javascript var Discogs = require('disconnect').Client; ```

Go!

Get the release data for a release with the id 176126. ```javascript var db = new Discogs().database(); db.getRelease(176126, function(err, data){
console.log(data);
}); ``` Set your own custom User-Agent. This is optional as when omitted disconnect will set a default one with the value DisConnectClient/x.x.x where x.x.x is the installed version of disconnect. ```javascript var dis = new Discogs('MyUserAgent/1.0'); ``` Get page 2 of USERNAME's public collection showing 75 releases. The second param is the collection folder ID where 0 is always the "All" folder. ```javascript var col = new Discogs().user().collection(); col.getReleases('USERNAME', 0, {page: 2, perpage: 75}, function(err, data){
console.log(data);
}); ```

Promises

When no callback is provided, the API functions return a native JS Promise
for easy chaining. ```javascript var db = new Discogs().database(); db.getRelease(1)
.then(function(release){ 
return db.getArtist(release.artists[0].id);
})
.then(function(artist){
console.log(artist.name);
});
```

Output format

User, artist and label profiles can be formatted in different ways: plaintext, html and discogs. disconnect defaults to discogs, but the output format can be set for each client instance. ```javascript // Set the output format to HTML var dis = new Discogs().setConfig({outputFormat: 'html'}); ```

Discogs Auth

Just provide the client constructor with your preferred way of authentication. ```javascript // Authenticate by user token var dis = new Discogs({userToken: 'YOURUSERTOKEN'}); // Authenticate by consumer key and secret var dis = new Discogs({
consumerKey: 'YOUR_CONSUMER_KEY', 
consumerSecret: 'YOUR_CONSUMER_SECRET'
}); ``` The User-Agent can still be passed for authenticated calls. ```javascript var dis = new Discogs('MyUserAgent/1.0', {userToken: 'YOURUSERTOKEN'}); ```

OAuth

Below are the steps that involve getting a valid OAuth access token from Discogs. Note that in the following examples the app variable is an Express instance to handle incoming HTTP requests.

  1. Get a request token

```javascript app.get('/authorize', function(req, res){
var oAuth = new Discogs().oauth();
oAuth.getRequestToken(
'YOUR_CONSUMER_KEY', 
'YOUR_CONSUMER_SECRET', 
'http://your-script-url/callback', 
function(err, requestData){
// Persist "requestData" here so that the callback handler can 
// access it later after returning from the authorize url
res.redirect(requestData.authorizeUrl);
}
);
}); ```

  1. Authorize

After redirection to the Discogs authorize URL in step 1, authorize the application.

  1. Get an access token

```javascript app.get('/callback', function(req, res){
var oAuth = new Discogs(requestData).oauth();
oAuth.getAccessToken(
req.query.oauth_verifier, // Verification code sent back by Discogs
function(err, accessData){
// Persist "accessData" here for following OAuth calls 
res.send('Received access token!');
}
);
}); ```

  1. Make OAuth calls

Simply provide the constructor with the accessData object persisted in step 3. ```javascript app.get('/identity', function(req, res){
var dis = new Discogs(accessData);
dis.getIdentity(function(err, data){
res.send(data);
});
}); ```

Images

Image requests themselves don't require authentication, but obtaining the image URLs through, for example, release data does. ```javascript var db = new Discogs(accessData).database(); db.getRelease(176126, function(err, data){
var url = data.images[0].resource_url;
db.getImage(url, function(err, data, rateLimit){
// Data contains the raw binary image data
require('fs').writeFile('/tmp/image.jpg', data, 'binary', function(err){
console.log('Image saved!');
});
});
}); ```

Resources

Discogs API documentation The OAuth Bible

License

MIT