From ba21977847181a3fc88c14a04312124080a46fbf Mon Sep 17 00:00:00 2001 From: Brian Beck Date: Wed, 15 Aug 2018 02:18:28 -0700 Subject: [PATCH] Update extension list in intro --- README.md | 84 +++++++++++++++++++++++++++++-------------------------- 1 file changed, 45 insertions(+), 39 deletions(-) diff --git a/README.md b/README.md index f404c3e..c5554cd 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ A [GraphQL][] schema, [Express][] server, and middleware for querying the [MusicBrainz][] API. It features an [extensible](./docs/extensions) schema to -add integration with Last.fm, fanart.tv, and more! +add integration with Discogs, Spotify, Last.fm, fanart.tv, and more! ```sh npm install graphbrainz --save @@ -22,7 +22,6 @@ npm install graphbrainz --save - - [Usage](#usage) - [As a standalone server](#as-a-standalone-server) - [As middleware](#as-middleware) @@ -89,11 +88,11 @@ app.listen(3000); The `graphbrainz` middleware function accepts the following options: -* **`client`**: A custom API client instance to use. See the +- **`client`**: A custom API client instance to use. See the [client submodule](src/api/client.js) 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. +- Any remaining options are passed along to the standard GraphQL middleware. See the [express-graphql][] documentation for more information. ### As a client @@ -104,53 +103,60 @@ or exposing a GraphQL endpoint, use the GraphBrainz schema with a library like GraphBrainz resolvers expect, like so: ```js -import { graphql } from 'graphql'; -import { MusicBrainz } from 'graphbrainz/lib/api'; -import createContext from 'graphbrainz/lib/context'; -import schema from 'graphbrainz/lib/schema'; +import { graphql } from 'graphql' +import { MusicBrainz } from 'graphbrainz/lib/api' +import createContext from 'graphbrainz/lib/context' +import schema from 'graphbrainz/lib/schema' -const client = new MusicBrainz(); +const client = new MusicBrainz() const context = createContext({ client }) -graphql(schema, ` - { - lookup { - releaseGroup(mbid: "99599db8-0e36-4a93-b0e8-350e9d7502a9") { - title +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); -}); + `, + 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 +- **`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, +- **`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 +- **`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 +- **`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 +- **`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 +- **`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 +- **`GRAPHBRAINZ_EXTENSIONS`**: A JSON array of module paths to load as [extensions](./docs/extensions). -* **`PORT`**: Port number to use, if running the standalone server. +- **`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 @@ -170,7 +176,7 @@ See the [debug][] package for more information. ## Example Queries -Nirvana albums and each album’s singles ([try it](https://graphbrainz.herokuapp.com/?query=query%20NirvanaAlbumSingles%20%7B%0A%20%20lookup%20%7B%0A%20%20%20%20artist(mbid%3A%20%225b11f4ce-a62d-471e-81fc-a69a8278c7da%22)%20%7B%0A%20%20%20%20%20%20name%0A%20%20%20%20%20%20releaseGroups(type%3A%20ALBUM)%20%7B%0A%20%20%20%20%20%20%20%20edges%20%7B%0A%20%20%20%20%20%20%20%20%20%20node%20%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20title%0A%20%20%20%20%20%20%20%20%20%20%20%20firstReleaseDate%0A%20%20%20%20%20%20%20%20%20%20%20%20relationships%20%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20releaseGroups(type%3A%20%22single%20from%22)%20%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20edges%20%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20node%20%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20target%20%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20...%20on%20ReleaseGroup%20%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20title%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20firstReleaseDate%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%7D%0A%20%20%20%20%7D%0A%20%20%7D%0A%7D%0A&operationName=NirvanaAlbumSingles)): +Nirvana albums and each album’s singles ([try it]()): ```graphql query NirvanaAlbumSingles { @@ -206,7 +212,7 @@ query NirvanaAlbumSingles { ### Pagination -The first five labels with “Apple” in the name ([try it](https://graphbrainz.herokuapp.com/?query=query%20AppleLabels%20%7B%0A%20%20search%20%7B%0A%20%20%20%20labels(query%3A%20%22Apple%22%2C%20first%3A%205)%20%7B%0A%20%20%20%20%20%20...labelResults%0A%20%20%20%20%7D%0A%20%20%7D%0A%7D%0A%0Afragment%20labelResults%20on%20LabelConnection%20%7B%0A%20%20pageInfo%20%7B%0A%20%20%20%20endCursor%0A%20%20%7D%0A%20%20edges%20%7B%0A%20%20%20%20cursor%0A%20%20%20%20node%20%7B%0A%20%20%20%20%20%20mbid%0A%20%20%20%20%20%20name%0A%20%20%20%20%20%20type%0A%20%20%20%20%20%20area%20%7B%0A%20%20%20%20%20%20%20%20name%0A%20%20%20%20%20%20%7D%0A%20%20%20%20%7D%0A%20%20%7D%0A%7D%0A&operationName=AppleLabels)): +The first five labels with “Apple” in the name ([try it]()): ```graphql query AppleLabels { @@ -235,7 +241,7 @@ fragment labelResults on LabelConnection { } ``` -…and the next five, using the `endCursor` from the previous result ([try it](https://graphbrainz.herokuapp.com/?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%22YXJyYXljb25uZWN0aW9uOjQ%3D%22)%20%7B%0A%20%20%20%20%20%20...labelResults%0A%20%20%20%20%7D%0A%20%20%7D%0A%7D%0A%0Afragment%20labelResults%20on%20LabelConnection%20%7B%0A%20%20pageInfo%20%7B%0A%20%20%20%20endCursor%0A%20%20%7D%0A%20%20edges%20%7B%0A%20%20%20%20cursor%0A%20%20%20%20node%20%7B%0A%20%20%20%20%20%20mbid%0A%20%20%20%20%20%20name%0A%20%20%20%20%20%20type%0A%20%20%20%20%20%20area%20%7B%0A%20%20%20%20%20%20%20%20name%0A%20%20%20%20%20%20%7D%0A%20%20%20%20%7D%0A%20%20%7D%0A%7D%0A&operationName=AppleLabels)): +…and the next five, using the `endCursor` from the previous result ([try it]()): ```graphql query AppleLabels { @@ -248,7 +254,7 @@ query AppleLabels { ``` Who the members of the band on an Apple Records release married, and when -([try it](https://graphbrainz.herokuapp.com/?query=query%20AppleRecordsMarriages%20%7B%0A%20%20search%20%7B%0A%20%20%20%20labels(query%3A%20%22Apple%20Records%22%2C%20first%3A%201)%20%7B%0A%20%20%20%20%20%20edges%20%7B%0A%20%20%20%20%20%20%20%20node%20%7B%0A%20%20%20%20%20%20%20%20%20%20name%0A%20%20%20%20%20%20%20%20%20%20disambiguation%0A%20%20%20%20%20%20%20%20%20%20country%0A%20%20%20%20%20%20%20%20%20%20releases(first%3A%201)%20%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20edges%20%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20node%20%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20title%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20date%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20artists%20%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20edges%20%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20node%20%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20name%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20...bandMembers%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%7D%0A%20%20%20%20%7D%0A%20%20%7D%0A%7D%0A%0Afragment%20bandMembers%20on%20Artist%20%7B%0A%20%20relationships%20%7B%0A%20%20%20%20artists(direction%3A%20%22backward%22%2C%20type%3A%20%22member%20of%20band%22)%20%7B%0A%20%20%20%20%20%20edges%20%7B%0A%20%20%20%20%20%20%20%20node%20%7B%0A%20%20%20%20%20%20%20%20%20%20type%0A%20%20%20%20%20%20%20%20%20%20target%20%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20...%20on%20Artist%20%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20name%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20...marriages%0A%20%20%20%20%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%7D%0A%20%20%20%20%7D%0A%20%20%7D%0A%7D%0A%0Afragment%20marriages%20on%20Artist%20%7B%0A%20%20relationships%20%7B%0A%20%20%20%20artists(type%3A%20%22married%22)%20%7B%0A%20%20%20%20%20%20edges%20%7B%0A%20%20%20%20%20%20%20%20node%20%7B%0A%20%20%20%20%20%20%20%20%20%20type%0A%20%20%20%20%20%20%20%20%20%20direction%0A%20%20%20%20%20%20%20%20%20%20begin%0A%20%20%20%20%20%20%20%20%20%20end%0A%20%20%20%20%20%20%20%20%20%20target%20%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20...%20on%20Artist%20%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20name%0A%20%20%20%20%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%7D%0A%20%20%20%20%7D%0A%20%20%7D%0A%7D%0A&operationName=AppleRecordsMarriages)): +([try it]()): ```graphql query AppleRecordsMarriages { @@ -320,7 +326,7 @@ fragment marriages on Artist { } ``` -Images of Tom Petty provided by various extensions ([try it](https://graphbrainz.herokuapp.com/?query=query%20TomPettyImages%20%7B%0A%20%20lookup%20%7B%0A%20%20%20%20artist(mbid%3A%20%225ca3f318-d028-4151-ac73-78e2b2d6cdcc%22)%20%7B%0A%20%20%20%20%20%20name%0A%20%20%20%20%20%20mediaWikiImages%20%7B%0A%20%20%20%20%20%20%20%20url%0A%20%20%20%20%20%20%20%20objectName%0A%20%20%20%20%20%20%20%20descriptionHTML%0A%20%20%20%20%20%20%20%20licenseShortName%0A%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20fanArt%20%7B%0A%20%20%20%20%20%20%20%20thumbnails%20%7B%0A%20%20%20%20%20%20%20%20%20%20url%0A%20%20%20%20%20%20%20%20%20%20likeCount%0A%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20theAudioDB%20%7B%0A%20%20%20%20%20%20%20%20logo%0A%20%20%20%20%20%20%20%20biography%0A%20%20%20%20%20%20%7D%0A%20%20%20%20%7D%0A%20%20%7D%0A%7D%0A&operationName=TomPettyImages)): +Images of Tom Petty provided by various extensions ([try it]()): ```graphql query TomPettyImages { @@ -407,15 +413,15 @@ third-party services. See the [Extensions](./docs/extensions) docs for more info. [demo]: https://graphbrainz.herokuapp.com/ -[Express]: http://expressjs.com/ -[MusicBrainz]: https://musicbrainz.org/ -[GraphQL]: http://graphql.org/ +[express]: http://expressjs.com/ +[musicbrainz]: https://musicbrainz.org/ +[graphql]: http://graphql.org/ [express-graphql]: https://www.npmjs.com/package/express-graphql [dotenv]: https://www.npmjs.com/package/dotenv [debug]: https://www.npmjs.com/package/debug -[GraphiQL]: https://github.com/graphql/graphiql +[graphiql]: https://github.com/graphql/graphiql [graphql-js]: https://github.com/graphql/graphql-js -[Relay]: https://facebook.github.io/relay/ +[relay]: https://facebook.github.io/relay/ [schema]: docs/schema.md [types]: docs/types.md [rate limiting]: https://musicbrainz.org/doc/XML_Web_Service/Rate_Limiting