{"id":25856596,"url":"https://github.com/defra/fcp-dal-api","last_synced_at":"2026-05-02T05:42:54.492Z","repository":{"id":279229394,"uuid":"938126676","full_name":"DEFRA/fcp-dal-api","owner":"DEFRA","description":"Git repository for service fcp-dal-api","archived":false,"fork":false,"pushed_at":"2025-02-24T13:15:43.000Z","size":134,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-24T14:28:06.149Z","etag":null,"topics":["backend","cdp","node","service"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DEFRA.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-02-24T13:15:27.000Z","updated_at":"2025-02-24T13:15:47.000Z","dependencies_parsed_at":"2025-02-24T14:28:20.483Z","dependency_job_id":"617c5a9d-4a1f-4485-a1cf-20f557159b56","html_url":"https://github.com/DEFRA/fcp-dal-api","commit_stats":null,"previous_names":["defra/fcp-dal-api"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DEFRA%2Ffcp-dal-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DEFRA%2Ffcp-dal-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DEFRA%2Ffcp-dal-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DEFRA%2Ffcp-dal-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DEFRA","download_url":"https://codeload.github.com/DEFRA/fcp-dal-api/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241404544,"owners_count":19957674,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["backend","cdp","node","service"],"created_at":"2025-03-01T18:19:10.086Z","updated_at":"2026-05-02T05:42:54.485Z","avatar_url":"https://github.com/DEFRA.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# fcp-dal-api\n\nThe Data Access Layer (DAL) for the Farming and Countryside Programme (FCP) - a GraphQL API.\n\n## Consumers' TL;DR\n\nThis README was created for project contributors; as a potential consumer of the DAL API, you probably only care about the following quick start steps:\n\n```bash\ncurl https://raw.githubusercontent.com/DEFRA/fcp-dal-api/refs/heads/main/compose.yml -o dal-api-compose.yml\ndocker compose -f dal-api-compose.yml up\n```\n\nThe graphQL explorer should now be available, head to http://localhost:3000/graphql in your browser, and have a play!\n\n\u003e NOTE: the IDs of the available customers and businesses can be found in the [mock code](https://github.com/DEFRA/fcp-dal-upstream-mock/blob/main/src/factories/id-lookups.js), along with their corresponding CRN or SBI (respectively), as well as the relationships between entities.\n\n\u003e NOTE: The above is a simplified setup that is intended to aid consumer development.\n\u003e For access to the live instances, [schema availability](#the-on-directive) and [authorisation](#security) would need to be carefully considered.\n\nMore consumer focused documentation can be found on the project [Homepage...](https://defra.github.io/fcp-dal-api/homepage)\n\n## Requirements\n\n- ### Node.js\n\n  The service is built in JavaScript code and requires [Node.js](http://nodejs.org/) `v22` or later, and [npm](https://nodejs.org/) `v11` or later (older versions will likely work, but are unsupported).\n\n- ### Docker\n\n  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.\n\n## Local development\n\n### Setup\n\nInstall application dependencies:\n\n```bash\nnpm install\n```\n\nEnsure the `.env` file exists. This can be copied from `.env.example`:\n\n```bash\ncp .env.example .env\n```\n\nAlso make sure to set the `KITS_INTERNAL_GATEWAY_URL` \u0026 `KITS_EXTERNAL_GATEWAY_URL` variable to the desired data source, e.g. for local testing:\n\n```env\nKITS_INTERNAL_GATEWAY_URL=http://localhost:3100/v1\nKITS_EXTERNAL_GATEWAY_URL=http://localhost:3101/v1\n```\n\nAlso you will need to run mongodb locally you can do this with the following command:\n\n```bash\ndocker-compose up -d mongodb\n```\n\n### Development\n\nTo run the application in `development` mode run:\n\n```bash\nnpm run dev\n```\n\nThis will spin up the API and automatically reload when changes are made to the API code.\n\n### KITS API mock\n\nThere is a local mock for the KITS API (the source of all the DAL's data).\nIt can be started by running:\n\n```bash\ndocker run -p 3100:3100 defradigital/fcp-dal-upstream-mock\n```\n\nThe code for the Mock can be found [here](https://github.com/DEFRA/fcp-dal-upstream-mock).\nThe `fixtures` folder is probably the most interesting, as this contains all the mock's raw data.\n\n### Testing\n\nTo test the application run:\n\n```bash\nnpm test\n```\n\n### Production\n\nTo mimic the application running in `production` mode locally run:\n\n```bash\ndocker compose up\n```\n\n### Npm scripts\n\nAll available Npm scripts can be seen in [package.json](./package.json).\nTo view them in your command line run:\n\n```bash\nnpm run\n```\n\n### Update dependencies\n\nTo update dependencies just run `npm it`! And commit any changes.\n\n### Formatting\n\n[Prettier](https://prettier.io/docs/) is used for all formatting (and syntax checking).\n[ESLint](https://eslint.org/docs/latest/) is used for linting and semantic checking (NOT formatting).\n\n#### Windows prettier issue\n\nIf you are having issues with formatting of line breaks on Windows update your global git config by running:\n\n```bash\ngit config --global core.autocrlf false\n```\n\n## API endpoints\n\n| Endpoint         | Description                                                                      |\n| :--------------- | :------------------------------------------------------------------------------- |\n| `GET: /health`   | Health check (should also be publicly available without auth on live envs).      |\n| `GET: /graphql`  | The interactive GraphQL service frontend (like Swagger docs but for GraphQL 😉). |\n| `POST: /graphql` | For making GraphQL requests to the DAL API.                                      |\n\n### The `@on` directive\n\nTo allow for the granular release of fields as data sources become available, fields must have the custom `@on` directive set to be included when the schema is built.\nOtherwise they will NOT be available in the graphQL queries, and an error will occur.\n\nFor example:\n\n```graphql\ntype Query {\n  customers: [Customer] @on\n}\n\ntype Customer {\n  id: ID! @on\n  name: String # this field is not included in the final schema\n}\n```\n\nFor local development and lower environments, all fields can be turned on by setting the env variable: `ALL_SCHEMA_ON=true`.\n\n### Security\n\nThe platform provides features for handling authentication to APIs.\nHowever, access to the DAL is handled differently.\nConsumers must first get an access token, which must be supplied in the `Authorization` header as part of every request.\n\n\u003e 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:\n\u003e\n\u003e - [dev](https://github.com/DEFRA/cdp-tf-svc-infra/blob/main/environments/dev/apis/fcp-dal-api.yml)\n\u003e - [test](https://github.com/DEFRA/cdp-tf-svc-infra/blob/main/environments/test/apis/fcp-dal-api.yml)\n\u003e - [ext-test](https://github.com/DEFRA/cdp-tf-svc-infra/blob/main/environments/ext-test/apis/fcp-dal-api.yml)\n\u003e - [perf-test](https://github.com/DEFRA/cdp-tf-svc-infra/blob/main/environments/perf-test/apis/fcp-dal-api.yml)\n\u003e - [prod](https://github.com/DEFRA/cdp-tf-svc-infra/blob/main/environments/prod/apis/fcp-dal-api.yml)\n\n## Development helpers\n\n### Proxy\n\nCPD uses a [forward-proxy](https://portal.cdp-int.defra.cloud/documentation/how-to/proxy.md) which is set up by default.\nModifications can be made by submitting a PR with changes to the relevant spec files:\n\n- [dev](https://github.com/DEFRA/cdp-squid-proxy/blob/main/configs/dev/fcp-dal-api.json)\n- [test](https://github.com/DEFRA/cdp-squid-proxy/blob/main/configs/test/fcp-dal-api.json)\n- [ext-test](https://github.com/DEFRA/cdp-squid-proxy/blob/main/configs/ext-test/fcp-dal-api.json)\n- [perf-test](https://github.com/DEFRA/cdp-squid-proxy/blob/main/configs/perf-test/fcp-dal-api.json)\n- [prod](https://github.com/DEFRA/cdp-squid-proxy/blob/main/configs/prod/fcp-dal-api.json)\n\n\u003e 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](./test_scripts/kits-testing-on-cdp.md).\n\n### SonarCloud\n\nThe project is setup with SonarCloud to ensure certain important code quality standards are met.\nMore information can be found [here](https://sonarcloud.io/project/overview?id=DEFRA_fcp-dal-api).\n\n### Dependabot - TODO!\n\nDecide whether to enable Depend-a-bot by renaming the [.github/example.dependabot.yml](.github/example.dependabot.yml) file to `.github/dependabot.yml` 🤷\n\n## Docker\n\n### Production image\n\nBuild:\n\n```bash\ndocker build --tag fcp-dal-api .\n```\n\nThen run:\n\n```bash\ndocker run -p 3000:3000 fcp-dal-api\n```\n\n### Docker Compose\n\nTo run the DAL API backed by the KITS API mock, run:\n\n```bash\ndocker compose up\n```\n\n## Licence\n\nTHIS INFORMATION IS LICENSED UNDER THE CONDITIONS OF THE OPEN GOVERNMENT LICENCE found at:\n\n\u003chttp://www.nationalarchives.gov.uk/doc/open-government-licence/version/3\u003e\n\nThe following attribution statement MUST be cited in your products and applications when using this information.\n\n\u003e Contains public sector information licensed under the Open Government license v3\n\n### About the licence\n\nThe Open Government Licence (OGL) was developed by the Controller of Her Majesty's Stationery Office (HMSO) to enable\ninformation providers in the public sector to license the use and re-use of their information under a common open\nlicence.\n\nIt is designed to encourage use and re-use of information freely and flexibly, with only a few conditions.\nThe 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.\n\nIt is designed to encourage use and re-use of information freely and flexibly, with only a few conditions.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdefra%2Ffcp-dal-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdefra%2Ffcp-dal-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdefra%2Ffcp-dal-api/lists"}