GraphBrainz

A [GraphQL][] schema, [Express][] server, and middleware for querying the [MusicBrainz][] API. It features an extensible schema to add integration with Discogs, Spotify, Last.fm, fanart.tv, and more!

[Try out the live demo!][demo] :bulb: Use the “Docs” sidebar, the [schema][], or the [types][] docs to help construct your query.

Support

Did this project bring you joy? Want to support updates? Check out my GitHub Sponsors page.

Alternatively…

Install

Install with npm:

npm install graphbrainz --save

Install with Yarn:

yarn add graphbrainz

GraphBrainz is written and distributed as native ECMAScript modules (ESM) and requires a compatible version of Node.js

Usage
Example Queries
- Pagination
Questions
Schema
- Extending the 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 { middleware as 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. You probably only need to do this if you want to adjust the rate limit and retry behavior.
Any remaining options are passed along to the standard GraphQL middleware. See the [express-graphql][] documentation for more information.

As a client

If you just want to make queries from your app without running a separate server or exposing a GraphQL endpoint, use the GraphBrainz schema with a library like [GraphQL.js][graphql-js]. You just need to create the context object that the GraphBrainz resolvers expect, like so:

import { graphql } from 'graphql';
import { MusicBrainz, createContext, baseSchema } from 'graphbrainz';

const client = new MusicBrainz();
const context = createContext({ client });

graphql(
  schema,
  `
    {
      lookup {
        releaseGroup(mbid: "99599db8-0e36-4a93-b0e8-350e9d7502a9") {
          title
        }
      }
    }
  `,
  null,
  context
)
  .then((result) => {
    const { releaseGroup } = result.data.lookup;
    console.log(`The album title is “${releaseGroup.title}”.`);
  })
  .catch((err) => {
    console.error(err);
  });

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_CORS_ORIGIN: The value of the origin option to pass to the [CORS][cors] middleware. Valid values are true to reflect the request origin, a specific origin string to allow, * to allow all origins, and false to disable CORS (the default).
GRAPHBRAINZ_CACHE_SIZE: The maximum number of REST API responses to cache. Increasing the cache size and TTL will greatly lower query execution time for complex queries involving frequently accessed entities. Defaults to 8192.
GRAPHBRAINZ_CACHE_TTL: The maximum age of REST API responses in the cache, in milliseconds. Responses older than this will be disposed of (and re-requested) the next time they are accessed. Defaults to 86400000 (one day).
GRAPHBRAINZ_GRAPHIQL: Set this to true if you want to force the [GraphiQL][] interface to be available even in production mode.
GRAPHBRAINZ_EXTENSIONS: A JSON array of module paths to load as extensions.
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. This just makes it more convenient to launch the server with certain settings. 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 (try it):

query NirvanaAlbumSingles {
  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
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

Pagination

The first five labels with “Apple” in the name (try it):

query AppleLabels {
  search {
    labels(query: "Apple", first: 5) {
      ...labelResults
    }
  }
}

fragment labelResults on LabelConnection {
  pageInfo {
    endCursor
  }
  edges {
    cursor
    node {
      mbid
      name
      type
      area {
        name
      }
    }
  }
}

…and the next five, using the endCursor from the previous result ([try it](<https://graphbrainz.fly.dev/?query=query%20AppleLabels%20%7B%0A%20%20search%20%7B%0A%20%20%20%20labels(query%3A%20%22Apple%22%2C%20first%3A%205%2C%20after%3A%20%22YXJyYXljb

Graphbrainz

Install / Use

README