Artsy's GraphQL API
Switch branches/tags
staging staging--2018-11-15--20-51-18 staging--2018-11-14--16-02-38 staging--2018-11-13--21-04-49 staging--2018-11-13--17-00-13 staging--2018-11-09--23-08-03 staging--2018-11-09--20-24-18 staging--2018-11-09--18-24-44 staging--2018-11-09--14-08-10 staging--2018-11-07--19-52-16 staging--2018-11-07--18-45-19 staging--2018-11-06--23-27-22 staging--2018-11-06--18-15-23 staging--2018-11-06--16-03-08 staging--2018-11-05--22-42-42 staging--2018-11-05--17-04-39 staging--2018-11-05--13-31-07 staging--2018-11-01--18-46-45 staging--2018-10-31--16-45-18 staging--2018-10-30--17-58-34 staging--2018-10-30--12-15-13 staging--2018-10-29--20-05-18 staging--2018-10-29--17-29-13 staging--2018-10-29--16-24-52 staging--2018-10-26--20-48-27 staging--2018-10-26--16-45-47 staging--2018-10-26--16-32-45 staging--2018-10-25--13-33-30 staging--2018-10-24--19-15-49 staging--2018-10-24--19-14-26 staging--2018-10-24--14-27-00 staging--2018-10-24--12-04-35 staging--2018-10-23--20-40-23 staging--2018-10-23--19-06-22 staging--2018-10-22--21-51-42 staging--2018-10-22--21-25-23 staging--2018-10-22--21-24-12 staging--2018-10-22--19-11-40 staging--2018-10-18--21-03-16 staging--2018-10-18--18-44-55 staging--2018-10-18--15-29-17 staging--2018-10-18--11-54-04 staging--2018-10-16--20-54-57 staging--2018-10-16--16-47-26 staging--2018-10-16--02-10-05 staging--2018-10-15--21-08-42 staging--2018-10-15--18-59-20 staging--2018-10-15--12-08-56 staging--2018-10-12--21-25-14 staging--2018-10-12--20-46-59 staging--2018-10-12--14-40-29 staging--2018-10-12--14-23-48 staging--2018-10-11--21-59-37 staging--2018-10-11--08-39-32 staging--2018-10-04--20-49-54 staging--2018-10-04--14-32-36 staging--2018-10-03--18-41-18 staging--2018-10-03--13-26-54 staging--2018-10-02--15-06-54 staging--2018-10-02--11-33-11 staging--2018-10-01--15-48-20 staging--2018-09-28--22-22-03 staging--2018-09-28--22-07-38 staging--2018-09-28--19-57-48 staging--2018-09-27--21-37-17 staging--2018-09-27--19-56-50 staging--2018-09-27--14-58-33 staging--2018-09-27--12-41-04 staging--2018-09-27--00-41-23 staging--2018-09-26--19-07-25 staging--2018-09-26--00-03-00 staging--2018-09-25--21-57-14 staging--2018-09-25--20-34-38 production production--2018-11-14--14-51-55 production--2018-11-06--22-13-47 production--2018-10-26--14-16-10 production--2018-10-16--13-41-18 production--2018-10-15--20-53-32 production--2018-10-01--16-47-11 production--2018-09-28--18-38-03
Nothing to show
Clone or download
Latest commit 61ce09a Nov 15, 2018
Failed to load latest commit information.
.circleci update hokusai version in circleci config Sep 25, 2018
.vscode Adds kaws graphql schema Oct 11, 2018
docs Rename the connection args -> grav args, and ensures the city shows, … Nov 6, 2018
hokusai adjust horizontal pod autoscaler parameters for metaphysiccs-web depl… Oct 26, 2018
patches [package] Update dd-trace to use our fork with connection tracing. Oct 3, 2018
scripts Switch out the default env vars now that stitching has been working f… Oct 29, 2018
src Merge pull request #1375 from dleve123/update-exchange-schema-after-s… Nov 14, 2018
.babelrc Update babel Sep 26, 2018
.dockerignore [docker] Ignore local build artefacts. Aug 24, 2018
.env.example Switch out the default env vars now that stitching has been working f… Oct 29, 2018
.env.test Switch out the default env vars now that stitching has been working f… Oct 29, 2018
.eslintignore Implement node interface for message type Jun 26, 2017
.eslintrc.json tweaked rules, fixed warning Jun 5, 2018
.gitignore Adds schema into the root of the repo, and updates it per-commit Sep 7, 2018
.nvmrc Update node version Nov 15, 2018
Brewfile Update the setup docs Aug 25, 2018
Dockerfile Update node version Nov 15, 2018
LICENSE license file Nov 20, 2015 switch cache to memcached driver Jun 13, 2018 Updates deployment docs. Oct 26, 2018
_schema.graphql Merge pull request #1375 from dleve123/update-exchange-schema-after-s… Nov 14, 2018
dangerfile.ts Switch out the default env vars now that stitching has been working f… Oct 29, 2018
global.d.ts [persisted queries] Lookup queries in JSON as initial implementation. Apr 9, 2018
index.js Add express-ipfilter and be able to use ENV to block by IP and range Aug 30, 2018
package.json Update node version Nov 15, 2018
redis.conf [cache] Switch from memcache to redis to get rid of memjs. Feb 15, 2018
tsconfig.json Remove unresovled editionset from Order Sep 20, 2018
wallaby.js Update and wrap up May 2, 2018
yarn.lock Allow filtering by attribution class for artworks Oct 10, 2018

Metaphysics CircleCI

Metaphysics is a GraphQL-compliant API that wraps various Artsy APIs. You can try it here against our staging API.

It is built on express, express-graphql, and graphql. With graphiql providing a sandbox to work with.

It is currently used in production all over the place in, and the Artsy iOS App


Getting Setup

To get yourself set up with all the project's dependencies:

git clone
cd metaphysics

# Install node modules
yarn install
# Installed system tools (like cache servers)
brew bundle
# Get set up with a default env
cp .env.example .env

For Artsy staff wanting to expand on your .env, you can use hokusai staging env get to see staging's env vars.


With your dependencies set up, you can run Metaphysics by running:

yarn dev

Which will start the server on http://localhost:5001

Recommended: You can run the commands inside the terminal in VS Code, then the debugger will be hooked up by default.

Setting up your local GraphiQL

We recommend the client for testing queries locally.

You will need to set up headers with both:

  • x-access-token - Evaluate sd.CURRENT_USER.accessToken in a dev console on (sign in first, obvs).
  • x-user-id - As above, but

Sample Queries

Once you have the GraphiQL client running against your local service, you can verify things are working by executing these queries:

Get popular artists

  popular_artists {
    artists {

Get your account information

  me {

If any of these queries fail, it's probable that you misconfigured your x-access-token or x-user-id HTTP headers.


Docker and Kubernetes setup

This is deployed using Hokusai to manage Docker and Kubernetes. To replicate this:

  • Install Docker for Mac and Hokusai

    $ brew tap caskroom/cask && brew cask install docker
    $ pip install hokusai

    If you are using your system Python distribution, you may need to run this as:

    $ sudo pip install hokusai --ignore-installed
  • Configure Hokusai

    $ hokusai configure --kubectl-version {{ kubectl_version }} --s3-bucket {{ kubectl_config_s3_bucket }} --s3-key {{ kubectl_config_s3_key }}
    $ hokusai check

    Artsy staff should find follow the instructions in


  • Run tests in the Docker Compose test stack via Hokusai:

    $ hokusai test
  • Or, to run tests locally: npm test to run the entire suite npm run watch to spin up the test watcher


PRs merged to the master branch are automatically deployed to staging. The release on staging can be promoted to production via the command hokusai pipeline promote --git-remote [upstream|origin]. The --git-remote option pushes a meaningful tag name to the git remote, so use whichever git remote points to Artsy's repository and not a fork (run git remote -v to see your git remotes and URLs). (If you accidentally push the git tags to the incorrect remote, you can run git push upstream production-tag-name to push a single tag to Artsy's repo.)

See Hokusai's docs on the Staging -> Production pipeline for more details.

Interacting with the staging and production deployments

Use hokusai staging commands to interact with the staging environment.

Use hokusai production commands to interact with the production environment.

(To deploy, see Deployment section above.)