GraphBrainz
A GraphQL schema, Express server, and middleware for querying theMusicBrainz API. It features an extensible schema toadd integration with Discogs, Spotify, Last.fm, fanart.tv, and more!
Try out the live demo!
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
Contents
Usage
This package can be used both as a standalone GraphQL server and as Expressmiddleware supplying a GraphQL endpoint.
As a standalone server
Run the included graphbrainz executable to start the server. The server isconfigured using environment variables.
$ graphbrainz
Listening on port 3000.
Development mode features like JSON pretty printing and the GraphiQLinterface will be enabled unless the server is run with NODE_ENV=production.
Note that if you are not running the standalone server within another Nodeproject, you may wish to install this package globally so that the graphbrainzscript is globally available:
npm install -g graphbrainz
As middleware
If you have an existing Express server and want to add this GraphQL service asan 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 theclient submodule for help with creating a custominstance. You probably only need to do this if you want to adjust the ratelimit and retry behavior.- Any remaining options are passed along to the standard GraphQL middleware. Seethe express-graphql documentation for more information.
As a client
If you just want to make queries from your app without running a separate serveror exposing a GraphQL endpoint, use the GraphBrainz schema with a library likeGraphQL.js. You just need to create the context object that theGraphBrainz 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 thisif you are running your own MusicBrainz mirror. Defaults tohttp://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 theoriginoption to pass to theCORS middleware. Valid values aretrueto reflect the requestorigin, a specific origin string to allow,*to allow all origins, andfalseto disable CORS (the default).GRAPHBRAINZ_CACHE_SIZE: The maximum number of REST API responses tocache. Increasing the cache size and TTL will greatly lower query executiontime for complex queries involving frequently accessed entities. Defaults to8192.GRAPHBRAINZ_CACHE_TTL: The maximum age of REST API responses in thecache, in milliseconds. Responses older than this will be disposed of (andre-requested) the next time they are accessed. Defaults to86400000(oneday).GRAPHBRAINZ_GRAPHIQL: Set this totrueif you want to force theGraphiQL interface to be available even in production mode.GRAPHBRAINZ_EXTENSIONS: A JSON array of module paths to load asextensions.PORT: Port number to use, if running the standalone server.
When running the standalone server, dotenv is used to load these variablesfrom a .env file, if one exists in the current working directory. This justmakes it more convenient to launch the server with certain settings. See thedotenv package for more information.
Debugging
The DEBUG environment variable can be used to enable logging for all (or justsome) 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):
query AppleLabels {
search {
labels(query: "Apple", first: 5, after: "YXJyYXljb25uZWN0aW9uOjQ=") {
...labelResults
}
}
}
Who the members of the band on an Apple Records release married, and when(try it):
query AppleRecordsMarriages {
search {
labels(query: "Apple Records", first: 1) {
edges {
node {
name
disambiguation
country
releases(first: 1) {
edges {
node {
title
date
artists {
edges {
node {
name
...bandMembers
}
}
}
}
}
}
}
}
}
}
}
fragment bandMembers on Artist {
relationships {
artists(direction: "backward", type: "member of band") {
edges {
node {
type
target {
... on Artist {
name
...marriages
}
}
}
}
}
}
}
fragment marriages on Artist {
relationships {
artists(type: "married") {
edges {
node {
type
direction
begin
end
target {
... on Artist {
name
}
}
}
}
}
}
}
Images of Tom Petty provided by various extensions(try it):
query TomPettyImages {
lookup {
artist(mbid: "5ca3f318-d028-4151-ac73-78e2b2d6cdcc") {
name
mediaWikiImages {
url
objectName
descriptionHTML
licenseShortName
}
fanArt {
thumbnails {
url
likeCount
}
}
theAudioDB {
logo
biography
}
}
}
}
You can find more example queries in the schema tests.
Questions
What’s with the cumbersome edges/node nesting? Why first/after insteadof limit/offset? Why mbid instead of id?
You can thank Relay for that; these are properties of a Relay-compliantschema. The schema was originally designed to be more user-friendly, but in theend I decided that being compatible with Relay was a worthwhile feature. Iagree, it’s ugly.
The GraphBrainz schema includes an extra nodes field on every connection type.If you only want the nodes and no other fields on edges, you can use nodesas a shortcut.
Don’t forget that you can also use GraphQL aliases to rename fieldsto your liking. For example, the following query renames edges, node, andmbid to results, releaseGroup, and id, respectively:
query ChristmasAlbums {
search {
releaseGroups(query: "Christmas") {
results: edges {
releaseGroup: node {
id: mbid
title
}
}
}
}
}
Why does my query take so long?
It’s likely that your query requires multiple round trips to the MusicBrainzREST API, which is subject to rate limiting. While the query resolver triesvery hard to fetch only the data necessary, and with the smallest number of APIrequests, it is not 100% optimal (yet). Make sure you are only requesting thefields you need and a reasonable level of nested entities – unless you arewilling to wait.
You can also set up a local MusicBrainz mirror and configureGraphBrainz to use that with no rate limiting.
Schema
The types document is the easiest to browse representation of the schema, oryou can read the schema in GraphQL syntax.
Extending the schema
The GraphBrainz schema can easily be extended to add integrations withthird-party services. See the Extensions docs for moreinfo.