fcp-dal-api

The Data Access Layer (DAL) for the Farming and Countryside Programme (FCP) - a GraphQL API.

Consumers' TL;DR

This README was created for project contributors; as a potential consumer of the DAL API, you probably only care about the following quick start steps:

curl https://raw.githubusercontent.com/DEFRA/fcp-dal-api/refs/heads/main/compose.yml -o dal-api-compose.yml
docker compose -f dal-api-compose.yml up

The graphQL explorer should now be available, head to http://localhost:3000/graphql in your browser, and have a play!

NOTE: the IDs of the available customers and businesses can be found in the mock code, along with their corresponding CRN or SBI (respectively), as well as the relationships between entities.

NOTE: The above is a simplified setup that is intended to aid consumer development. For access to the live instances, schema availability and authorisation would need to be carefully considered.

More consumer focused documentation can be found on the project Homepage...

Requirements

• Node.js

  The service is built in JavaScript code and requires Node.js v22 or later, and npm v11 or later (older versions will likely work, but are unsupported).

• Docker

  A modern version of docker (with the compose extensions) will allow a local environment to be simply run. This will mimic the live services, and facilitate development and testing.

Local development

Setup

Install application dependencies

Install application dependencies:

npm install

Implicit lifecycle scripts are disabled

Due to the prevalence of NPM supply-chain attacks, scripts that would usually be run during npm install (and also pre/post scripts that are run alongside the target script) have been forcibly disabled with the following setting in .npmrc:

ignore-scripts=true

All required post install steps have been gathered into a postinstall script. This script contains calls to commands that would have been run by 3rd party library installers, if ignore-scripts had not been set. These commands in this file have been limited to those that are required for our build process. It would still be prudent to examine this script, prior to running to ensure that you understand what will be run (you will be prompted to confirm at each step). To run this script, execute the following:

npm run postinstall

3rd party libraries must be at least 7 days old before they can be installed

The .npmrc setting below prevents libraries that have been released in the past 7 days from being installed.

min-release-age=7

This gives the npm community time to detect a compromised release before this repo consumes it.

This does create a potential issue. If npm audit identifies an issue that must be fixed, and the patched library has been released less than 7 days ago, then you will need to investigate the library in question:

• Look at the published release
• Verify that it's safe
• Run npm install {your-dependency}@{version-number} --min-release-age=0 (including --save-dev if it's a dev only dependency)

Setup environment file

Ensure the .env file exists. This can be copied from .env.example:

cp .env.example .env

Also make sure to set the upstream datasource, e.g. for local testing against mock running in docker:

KITS_INTERNAL_GATEWAY_URL=http://localhost:3100/v1
KITS_EXTERNAL_GATEWAY_URL=http://localhost:3100/v1
HITACHI_BASE_URL=http://localhost:3100/api

Start mongo

You will need to run mongodb locally. You can do this with the following command:

docker-compose up -d mongodb

Development

To run the application in development mode run:

npm run dev

This will spin up the API and automatically reload when changes are made to the API code.

KITS API mock

There is a local mock for the KITS API (the source of all the DAL's data). It can be started by running:

docker run -p 3100:3100 defradigital/fcp-dal-upstream-mock

The code for the Mock can be found here. The fixtures folder is probably the most interesting, as this contains all the mock's raw data.

Testing

To test the application run:

npm test

Production

To mimic the application running in production mode locally run:

docker compose up

Npm scripts

All available Npm scripts can be seen in package.json. To view them in your command line run:

npm run

Update dependencies

To update dependencies just run npm it! And commit any changes.

Formatting

Prettier is used for all formatting (and syntax checking). ESLint is used for linting and semantic checking (NOT formatting).

Windows prettier issue

If you are having issues with formatting of line breaks on Windows update your global git config by running:

git config --global core.autocrlf false

API endpoints

Endpoint	Description
GET: /health	Health check (should also be publicly available without auth on live envs).
GET: /graphql	The interactive GraphQL service frontend (like Swagger docs but for GraphQL 😉).
POST: /graphql	For making GraphQL requests to the DAL API.

The @wip directive

The @wip directive marks fields that are still a work in progress. It is only valid on field definitions:

directive @wip on FIELD_DEFINITION

Fields annotated with @wip behave differently depending on the environment:

• In dev and perf-test, the fields are included in the schema but are marked as deprecated with the reason: Work in progress — may change or be removed.
• In all other environments (test, ext-test, prod), the fields are removed entirely from the schema.

Note: dev and perf-test are the environments backed by the upstream mock service (rather than a real KITS or Hitachi instance). The @wip directive is only active in these mock-backed environments.

This allows WIP functionality to be safely exercised in supported environments without exposing it to consumers elsewhere.

Example usage:

type Query {
  customers: [Customer]
  experimentalFeature: String @wip
}

type Customer {
  id: ID!
  name: String
  wipOnlyField: Int @wip
}

In non-WIP environments, Query.experimentalFeature and Customer.wipOnlyField will not exist in the schema. In dev and perf-test they will be present (with the deprecation reason).

Security

The platform provides features for handling authentication to APIs. However, access to the DAL is handled differently. Consumers must first get an access token, which must be supplied in the Authorization header as part of every request.

NOTE: all endpoints (expect posts to /graphql) are protected by default. Modifications can be made by submitting a PR with changes to the relevant spec files:

• dev
• test
• ext-test
• perf-test
• prod

Development helpers

Proxy

CPD uses a forward-proxy which is set up by default. Modifications can be made by submitting a PR with changes to the relevant spec files:

• dev
• test
• ext-test
• perf-test
• prod

NOTE: to ensure the proxy has been correctly configured, connections to the API's data source (KITS) can be tested by following the steps in this guide.

SonarCloud

The project is setup with SonarCloud to ensure certain important code quality standards are met. More information can be found here.

Dependabot - TODO!

Decide whether to enable Depend-a-bot by renaming the .github/example.dependabot.yml file to .github/dependabot.yml 🤷

Docker

Production image

Build:

docker build --tag fcp-dal-api .

Then run:

docker run -p 3000:3000 fcp-dal-api

Docker Compose

To run the DAL API backed by the KITS API mock, run:

docker compose up

Licence

THIS INFORMATION IS LICENSED UNDER THE CONDITIONS OF THE OPEN GOVERNMENT LICENCE found at:

http://www.nationalarchives.gov.uk/doc/open-government-licence/version/3

The following attribution statement MUST be cited in your products and applications when using this information.

Contains public sector information licensed under the Open Government license v3

About the licence

The Open Government Licence (OGL) was developed by the Controller of Her Majesty's Stationery Office (HMSO) to enable information providers in the public sector to license the use and re-use of their information under a common open licence.

It is designed to encourage use and re-use of information freely and flexibly, with only a few conditions. The Open Government Licence (OGL) was developed by the Controller of Her Majesty's Stationery Office (HMSO) to enable information providers in the public sector to license the use and re-use of their information under a common open licence.

It is designed to encourage use and re-use of information freely and flexibly, with only a few conditions.