graphbrainz

An Express server and middleware for querying MusicBrainz using GraphQL.

npm install graphbrainz --save

Try out the live demo! Use the “Docs” sidebar or see the schema to help construct your query.

Contents

• Usage
  • As a standalone server
  • As middleware
  • Environment Variables
  • Debugging
• Example Queries
• Questions
• Schema

Usage

This package can be used both as a standalone GraphQL server and as Express middleware supplying a GraphQL endpoint.

As a standalone server

Run the included graphbrainz executable to start the server. The server is configured using environment variables.

$ graphbrainz
Listening on port 3000.

Development mode features like JSON pretty printing and the GraphiQL interface will be enabled unless the server is run with NODE_ENV=production.

Note that if you are not running the standalone server within another Node project, you may wish to install this package globally so that the graphbrainz script is globally available:

npm install -g graphbrainz

As middleware

If you have an existing Express server and want to add this GraphQL service as an endpoint, or you just want more customization, use the middleware.

import express from 'express';
import graphbrainz from 'graphbrainz';

const app = express();

// Use the default options:
app.use('/graphbrainz', graphbrainz());

// or, pass some options:
app.use('/graphbrainz', graphbrainz({
  client: new MusicBrainz({ ... }),
  graphiql: true,
  ...
}));

app.listen(3000);

The graphbrainz middleware function accepts the following options:

• client: A custom API client instance to use. See the client submodule for help with creating a custom instance.
• Any remaining options are passed along to the standard GraphQL middleware. See the express-graphql documentation for more information.

Environment Variables

• MUSICBRAINZ_BASE_URL: The base MusicBrainz API URL to use. Change this if you are running your own MusicBrainz mirror. Defaults to http://musicbrainz.org/ws/2/.
• GRAPHBRAINZ_PATH: The URL route at which to expose the GraphQL endpoint, if running the standalone server. Defaults to /.
• GRAPHBRAINZ_GRAPHIQL: Set this to true if you want to force the GraphiQL interface to be available even in production mode.
• PORT: Port number to use, if running the standalone server.

When running the standalone server, dotenv is used to load these variables from a .env file, if one exists in the current working directory. See the dotenv package for more information.

Debugging

The DEBUG environment variable can be used to enable logging for all (or just some) of this package’s submodules:

$ DEBUG=graphbrainz:* graphbrainz

See the debug package for more information.

Example Queries

Nirvana albums and each album’s singles:

{
  lookup {
    artist(mbid: "5b11f4ce-a62d-471e-81fc-a69a8278c7da") {
      name
      releaseGroups(type: ALBUM) {
        edges {
          node {
            title
            firstReleaseDate
            relationships {
              releaseGroups(type: "single from") {
                edges {
                  node {
                    target {
                      ... on ReleaseGroup {
                        title
                        firstReleaseDate
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

Questions

What’s with the cumbersome edges / node nesting? Why mbid instead of id?

You can thank Relay for that; these are properties of a Relay-compliant schema. The schema was originally designed without these annoyances, but in the end I decided that being compatible with Relay was a worthwhile feature.

Schema

See the GraphQL schema.