README.md

CharityBase GraphQL API

• Using the API
  • Playground
  • Endpoint
  • Versioning
  • Authorization
  • Response
• Working on the API
  • Installing
  • Developing
  • Deploying
    • Prod Environment Variables

Using the API

Playground

For testing queries and viewing the interactive docs, use the GraphiQL interface.

Endpoint

The API has a single endpoint:

https://charitybase.uk/api/graphql

As described in the GraphQL docs you can send either a GET or POST request and the query string can either be written in the url or in the body (if using POST).

Versioning

The API is versionless - we won't introduce any breaking changes. What?!

Authorization

Whether using GET or POST, send your API key in an Authorization header like so:

"Authorization": "Apikey 9447fa04-c15b-40e6-92b6-30307deeb5d1"

Replace the above key with your own (available from the API Portal) and be sure to keep the Apikey prefix as above.

Response

A JSON body response is returned of the form:

{
  "data": { ... }, // not present if the request query was badly formed
  "errors": [ ... ] // not present if there were no errors
}

The response has a status code of 200 (even if errors occured) unless the query was badly formed in which case the status code is 400.

Conveniently the data object has the same shape as the query sent in the request.

Working on the API

Installing

yarn # or npm install
cp .env-example .env # then update variables in .env

Note: variables already in your environment (e.g. in .bash_profile) will override those in .env

Developing

yarn dev

Deploying

yarn deploy:production

Note: this requires Now which can be installed globally with npm: npm i -g now

Prod Environment Variables

To ensure our sensitive environment variables are only accessible by the API code, we store them as Now secrets. This is achieved on the command line:

now secret add charity-base-es-aws-access-key-id example-key-id
now secret add charity-base-es-aws-secret-access-key example-secret-key
...

The environment variable names are mapped to the secret names in env in now.json. Note the @ prefixing each secret name.