charity-base / charity-base-api

CharityBase GraphQL API

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.

charity-base-api's Issues

Can't get API keys

After login to get API keys, shows message "error oops"

Rate limit?

Hi,

I'm working on a wrapper for R. I couldn't see a rate limit information. Do you have a reasonable limit in mind that you suggest I build in to the wrapper?

Best,
Oguzhan

Gift Aid Eligibility

I see from https://register-of-charities.charitycommission.gov.uk/charity-search/-/charity-details/5046241/governance that there is now a GiftAid eligibility field.

It is not a field I can see on the annual return form: https://assets.publishing.service.gov.uk/government/uploads/system/uploads/attachment_data/file/883985/Annual_return_questions_web__odt_Feb2020_2_.odt

However, since this is regulated by HMRC and not CCEW then they may be pulling this information from HMRC sources.

It would help to have this information available. I am not sure whether this gets exported, I will check, where is it I can look.

Unit tests

hey @dan-kwiat, was looking at your task list and @ivanmauricio were thinking of making a start on the testing.

How would you feel about using tape vs mocha and chai?

https://medium.com/javascript-scene/why-i-use-tape-instead-of-mocha-so-should-you-6aa105d8eaf4#.kchsyf52a

Not all Charity Commission data is included

The profile pages for individual charities in the Charity Commission web site include fields detailing Aims and Activities, What the Charity Does, Who the Charity Helps, and How the Charity Works, but I can't find these in your schema. Is there some reason for this? Might they be added in future?

Scottish Charity Data

It's mentioned as a potential future feature on your website but it would be incredible if the Scottish Charity Commission data could also be requested.