{"id":23421392,"url":"https://github.com/nhsdigital/personal-demographics-service-api","last_synced_at":"2026-04-24T10:01:25.707Z","repository":{"id":38302667,"uuid":"234322362","full_name":"NHSDigital/personal-demographics-service-api","owner":"NHSDigital","description":"Specifications for NHS Digital APIs provided on the API Management Platform","archived":false,"fork":false,"pushed_at":"2026-04-15T14:29:03.000Z","size":9544,"stargazers_count":27,"open_issues_count":21,"forks_count":16,"subscribers_count":41,"default_branch":"master","last_synced_at":"2026-04-15T14:33:09.597Z","etag":null,"topics":["openapi","swagger"],"latest_commit_sha":null,"homepage":"","language":"Gherkin","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/NHSDigital.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2020-01-16T13:09:16.000Z","updated_at":"2026-04-15T13:13:41.000Z","dependencies_parsed_at":"2026-02-24T13:01:46.894Z","dependency_job_id":null,"html_url":"https://github.com/NHSDigital/personal-demographics-service-api","commit_stats":null,"previous_names":[],"tags_count":853,"template":false,"template_full_name":null,"purl":"pkg:github/NHSDigital/personal-demographics-service-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NHSDigital%2Fpersonal-demographics-service-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NHSDigital%2Fpersonal-demographics-service-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NHSDigital%2Fpersonal-demographics-service-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NHSDigital%2Fpersonal-demographics-service-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/NHSDigital","download_url":"https://codeload.github.com/NHSDigital/personal-demographics-service-api/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NHSDigital%2Fpersonal-demographics-service-api/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32218290,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-24T09:47:08.147Z","status":"ssl_error","status_checked_at":"2026-04-24T09:46:41.165Z","response_time":64,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["openapi","swagger"],"created_at":"2024-12-23T02:14:59.709Z","updated_at":"2026-04-24T10:01:25.702Z","avatar_url":"https://github.com/NHSDigital.png","language":"Gherkin","funding_links":[],"categories":[],"sub_categories":[],"readme":"# personal-demographics-service-api\n\n![Build](https://github.com/NHSDigital/personal-demographics-service-api/workflows/Build/badge.svg?branch=master)\n\u003cimg alt=\"gitleaks badge\" src=\"https://img.shields.io/badge/protected%20by-gitleaks-blue\"\u003e\n\nThis is a RESTful HL7® FHIR® API for the *Personal Demographics Service*.\n\nIt includes:\n* `karate-tests/` - our functional e2e API tests implemented using the Karate framework. [There is a separate readme for these tests at the moment](karate-tests/README.md)\n* `specification/` - an [Open API Specification](https://swagger.io/docs/specification/about/) describing the endpoints, methods and messages exchanged by the API. Use it to generate interactive documentation; the contract between the API and its consumers.\n* `sandbox/` - a Karate API mock application. Use it as a back-end service to the interactive documentation to illustrate interactions and concepts. It is not intended to provide an exhaustive/faithful environment suitable for full development and testing.\n* `scripts/` - utilities helpful to developers of this specification.\n* `apiproxy/` - the API proxy, which is deployed to our API platform hosted on Google Apigee Edge\n\nConsumers of the API will find developer documentation on the [NHS Digital Developer Hub](https://digital.nhs.uk/developer/api-catalogue/personal-demographics-service-fhir).\n\nThis repo does *not* include the PDS FHIR API back-end. That is part of 'Core Spine' which is not currently open source.\n\n## Contributing\nContributions to this project are welcome from anyone, providing that they conform to the [guidelines for contribution](https://github.com/NHSDigital/personal-demographics-service-api/blob/master/CONTRIBUTING.md) and the [community code of conduct](https://github.com/NHSDigital/personal-demographics-service-api/blob/master/CODE_OF_CONDUCT.md).\n\n### Licensing\nThis code is dual licensed under the MIT license and the OGL (Open Government License). Any new work added to this repository must conform to the conditions of these licenses. In particular this means that this project may not depend on GPL-licensed or AGPL-licensed libraries, as these would violate the terms of those libraries' licenses.\n\nThe contents of this repository are protected by Crown Copyright (C).\n\n## Setup\n\nN.B. that some functionality requires environment variables to be set. Some of these are described lower down in the readme, whilst others can be found in [the environment variables section of this confluence page](https://nhsd-confluence.digital.nhs.uk/display/SPINE/Personal+Demographics+Service+api+setup)\n\n\nWindows users should install [Windows Subsystem for Linux (WSL)](https://learn.microsoft.com/en-us/windows/wsl/install). Any distro is fine, though ubuntu/debian are recommended.\n\n## Installing requirements\nInstall build requirements. This will make sure you don't hit any weird python issues later.\n```bash\nsudo apt update\nsudo apt install make build-essential libssl-dev zlib1g-dev libbz2-dev libreadline-dev libsqlite3-dev wget curl llvm libncurses5-dev libncursesw5-dev xz-utils tk-dev libffi-dev liblzma-dev git net-tools python-openssl\n```\nIf you get the error \"Unable to locate package python-openssl\", try\n```bash\nsudo apt install python3-openssl\n```\n\nInstall [pyenv](https://github.com/pyenv/pyenv) using the code below and then follow their [guide](https://github.com/pyenv/pyenv#set-up-your-shell-environment-for-pyenv) to integrate it with your terminal\n```bash\ncurl https://pyenv.run | bash\nexec $SHELL\n```\nIf the command isn't working you can also [try the instructions here.](https://www.liquidweb.com/kb/how-to-install-pyenv-on-ubuntu-18-04/)\n\nInstall python 3.13\n```bash\npyenv install 3.13\n```\nEither set this as your global python (if this is not incompatible with your other projects),\n```bash\npyenv global 3.13\n```\nor local to repository, if there is not a python-version file installed (you might have to raise a PR to add the file that's created).\n```bash\npyenv local 3.13\npython --version\n```\n\nInstall poetry, then run 'poetry install' to install dependencies. Makes sure you change directory to this repo.\n```bash\ncurl -sSL https://install.python-poetry.org | python3\npoetry install\n```\n\nInstall nvm \u0026 npm\n```bash\ncurl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.35.2/install.sh | bash\n# Close and reopen your terminal window, or use 'exec $SHELL'\nnvm install lts/iron\nnvm use lts/iron\nnpm --version\n```\n\nInstall Java\n```bash\nsudo apt install default-jre default-jdk\njava -version\n```\n\nInstall pytest\n```bash\npip install -U pytest\nsudo apt-get update\nsudo apt-get install jq\n```\n\nInstall shellcheck (we use this for linting .sh files)\n```bash\nsudo apt install shellcheck\n```\n\nInstall gitleaks (we use this for scanning for secrets)\n* Extract gitleaks tarball to /usr/local/bin\n```bash\ncd ~/Downloads\ncurl -LO https://github.com/gitleaks/gitleaks/releases/download/v8.27.0/gitleaks_8.27.0_linux_x64.tar.gz\nsudo tar -xvzf gitleaks_8.27.0_linux_x64.tar.gz -C /usr/local/bin gitleaks\n```\n* Ensure that /usr/local/bin is part of your $PATH environment variable\n```bash\necho $PATH\n```\n* If it does not exist in the output, then add the following line to .bashrc file\n```bash\nexport PATH=\"/usr/local/bin:$PATH\"\n```\n* You may need to open a new terminal/vscode for these changes to take affect\n\nNext open powershell and get the wsl ip (make sure wsl is running)\nThe purpose of the following instructions is to enable you to use postman if you wish against the sandbox.\n```bash\nwsl hostname -i\n```\nAdd a proxy and open the windows fire wall, replace [PORT] with the port you want to connect to.\nconnected address is the ip wsl is operating on (from `wsl hostname -i`)\n```bash\nnetsh interface portproxy add v4tov4 listenport=9000 listenaddress=0.0.0.0 connectport=[PORT] connectaddress=127.0.1.1\n# Check it's been added\nnetsh interface portproxy show v4tov4\nfirewall -add port 9000 \n```\n\n## Development\n\n\n#### Updating hooks\nYou can install some pre-commit hooks to ensure you can't commit invalid spec changes by accident. These are also run\nin CI, but it's useful to run them locally too.\n\n```bash\nmake install-hooks\n```\n\n### Environment Variables\nVarious scripts and commands rely on environment variables being set. These are documented with the commands.\n\n:bulb: Consider using [direnv](https://direnv.net/) to manage your environment variables during development and maintaining your own `.envrc` file - the values of these variables will be specific to you and/or sensitive.\n\n### Make commands\nThere are `make` commands that alias some of this functionality:\n * `lint` -- Lints the spec and code\n * `publish` -- Outputs the specification as a **single file** into the `dist/` directory\n * `serve` -- Serves a preview of the specification in human-readable format\n * `generate-examples` -- generate example objects from the specification\n * `validate` -- validate generated examples against FHIR R4\n\n### Running tests\n#### Sandbox Tests\n\nRun the install command if not ran already\n```bash\nmake install\n```\n\nTo run the tests against a local version of the sandbox, use:\n```bash\nmake test-local-sandbox\n```\n\nTo run the tests against the production sandbox, us:\n```bash\nmake test-sandbox\n```\n\n#### Jest\n\nA short javascript file, RestrictRequests.js, handles restricting patient-access requests. Jest is use to unit test this file. To run these tests locally,\n```\nnpm run jest\n```\n\n\n### VS Code Plugins\n\n * [openapi-lint](https://marketplace.visualstudio.com/items?itemName=mermade.openapi-lint) resolves links and validates entire spec with the 'OpenAPI Resolve and Validate' command\n * [OpenAPI (Swagger) Editor](https://marketplace.visualstudio.com/items?itemName=42Crunch.vscode-openapi) provides sidebar navigation\n * [ESLint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) useful helper when you're working with JavaScript files\n\n### Emacs Plugins\n\n * [**openapi-yaml-mode**](https://github.com/esc-emacs/openapi-yaml-mode) provides syntax highlighting, completion, and path help\n\n### Redocly\n\n\u003e [Redocly](https://redocly.com/) *Beautiful API documentation loved by teams and API consumers. Brought to you by the open-source extraordinaires behind Redoc*\n\nRedocly does the lifting for the following npm scripts:\n\n * `lint` -- Lints the definition\n * `publish` -- Outputs the specification as a **single file** into the `dist/` directory\n * `serve` -- Serves a preview of the specification in human-readable format\n\n(Workflow detailed in a [post](https://developerjack.com/blog/2018/maintaining-large-design-first-api-specs/) on the *developerjack* blog.)\n\n:bulb: The `publish` command is useful when uploading to Apigee which requires the spec as a single file.\n\n### Caveats\n\n#### Swagger UI\nSwagger UI unfortunately doesn't correctly render `$ref`s in examples, so use `speccy serve` instead.\n\n#### Apigee Portal\nThe Apigee portal will not automatically pull examples from schemas, you must specify them manually.\n\n### Postman Collection\n\n`Patient Demographics Sandbox.postman_collection` must be kept in sync with the OAS and Sandbox manually.\n\nProcedure:\n * Log in to the Postman account\n * Update requests\n * Export the collection back into the repo\n\n The link in `personal-demographics.yaml` will get the most recent version of the collection.\n\n## Deployment\n\n### Specification\nUpdate the API Specification and derived documentation in the Portal.\n\n`make deploy-spec` with environment variables:\n\n* `APIGEE_USERNAME`\n* `APIGEE_PASSWORD`\n* `APIGEE_SPEC_ID`\n* `APIGEE_PORTAL_API_ID`\n\n### API Proxy \u0026 Sandbox Service\nRedeploy the API Proxy and hosted Sandbox service.\n\n`make deploy-proxy` with environment variables:\n\n* `APIGEE_USERNAME`\n* `APIGEE_PASSWORD`\n* `APIGEE_ORGANIZATION`\n* `APIGEE_ENVIRONMENTS` - Comma-separated list of environments to deploy to (e.g. `test,prod`)\n* `APIGEE_APIPROXY` - Name of the API Proxy for deployment\n* `APIGEE_BASE_PATH` - The proxy's base path (must be unique)\n\n:bulb: Specify your own API Proxy (with base path) for use during development.\n\n#### Platform setup\n\nSuccessful deployment of the API Proxy requires:\n\n 1. *Target Servers*:\n    1. `spine-demographics`: Gateway to PDS API\n    2. `spine-demographics-int` Gateway to PDS INT API (Only avaliable for pull requests)\n    3. `identity-server` - Identity Provider's OAuth server\n 2. An **encrypted** (for production) *Key-Value Map* named `pds-variables-encrypted`, containing:\n    1. Key: `NHSD-ASID`, Value: Accredited System ID (ASID) identifying the API Gateway\n 3. A *Key-Value Map* named `pds-variables`, containing:\n    1. Key: `jwks_path`, Value: Path on `identity-server` Target Server to JSON Web Key Set (JWKS)\n\n:bulb: For Sandbox-running environments (`test`) these need to be present for successful deployment but can be set to empty/dummy values.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnhsdigital%2Fpersonal-demographics-service-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnhsdigital%2Fpersonal-demographics-service-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnhsdigital%2Fpersonal-demographics-service-api/lists"}