CharityBase GraphQL API

• Using the API
  • Playground
  • Endpoint
  • Versioning
  • Authorization
  • Response
• Working on the API
  • Development
    • Dev Environment Variables
  • Deployment
    • 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

Development

yarn dev

Dev Environment Variables

Expected environment variables are listed in env in now.json. You may define them in a .env as follows:

# example .env file in charity-base-api
CHARITY_BASE_ES_AWS_ACCESS_KEY_ID=example-key-id
CHARITY_BASE_ES_AWS_SECRET_ACCESS_KEY=example-secret-key
...

Note: these values will not override any environment variables already set e.g. in your .bash_profile.

Deployment

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.