{"id":23421347,"url":"https://github.com/nhsdigital/spine-directory-service-api","last_synced_at":"2025-04-12T14:05:29.026Z","repository":{"id":37798009,"uuid":"276146749","full_name":"NHSDigital/spine-directory-service-api","owner":"NHSDigital","description":null,"archived":false,"fork":false,"pushed_at":"2024-04-12T16:24:26.000Z","size":1866,"stargazers_count":6,"open_issues_count":7,"forks_count":3,"subscribers_count":44,"default_branch":"master","last_synced_at":"2024-04-14T05:38:24.884Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","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":"CHANGELOG.md","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}},"created_at":"2020-06-30T16:00:54.000Z","updated_at":"2024-08-12T14:20:31.571Z","dependencies_parsed_at":"2024-04-15T09:45:18.178Z","dependency_job_id":"cb8bf9b1-1e9d-4ea7-beb1-f4f431cdf8f2","html_url":"https://github.com/NHSDigital/spine-directory-service-api","commit_stats":null,"previous_names":[],"tags_count":159,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NHSDigital%2Fspine-directory-service-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NHSDigital%2Fspine-directory-service-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NHSDigital%2Fspine-directory-service-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NHSDigital%2Fspine-directory-service-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/NHSDigital","download_url":"https://codeload.github.com/NHSDigital/spine-directory-service-api/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248578860,"owners_count":21127713,"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":[],"created_at":"2024-12-23T02:14:53.648Z","updated_at":"2025-04-12T14:05:29.019Z","avatar_url":"https://github.com/NHSDigital.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Spine Directory Service\n\n![Build](https://github.com/NHSDigital/spine-directory-service-api/workflows/Build/badge.svg?branch=master)\n\nThis is a RESTful HL7® FHIR® API specification for the *Spine Directory Service API*.\n\n* `specification/` This [Open API Specification](https://swagger.io/docs/specification/about/) describes the endpoints, methods and messages exchanged by the API. Use it to generate interactive documentation; the contract between the API and its consumers.\n* `docker/sds-api/` This implements a mock implementation of the service. 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* `proxies/` Live (connecting to another service) and sandbox (using the sandbox container) Apigee API Proxy definitions.\n\nConsumers of the API will find developer documentation on the [NHS Digital Developer Hub](https://portal.developer.nhs.uk/docs/spine-directory-service-int/1/overview).\n\n## Contributing\n\nContributions to this project are welcome from anyone, providing that they conform to the [guidelines for contribution](https://github.com/NHSDigital/spine-directory/blob/master/CONTRIBUTING.md) and the [community code of conduct](https://github.com/NHSDigital/spine-directory/blob/master/CODE_OF_CONDUCT.md).\n\n### Licensing\n\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## Development\n\n### Requirements\n\n* make\n* nodejs + npm/yarn\n* [poetry](https://github.com/python-poetry/poetry)\n\n### Install\n\n```\nmake install\n```\n\n### Local Install\n\n```sh\ncd docker/sds-api/spine-directory-service/sds\npython3 -m venv .venv\npipenv install\nsource .venv/bin/activate\n```\n\nMake sure VSCode is using the correct interpreter inside your .venv folder.\n\nUpdate CPM_CLIENT_KEY to use your client key for accessing cpm in launch.json\n\n```\n\"CPM_CLIENT_KEY\": \"YOUR_API_KEY_GOES_HERE\"\n```\n\nThen you can run the VSCode debugger.\n\n### Local Docker Install\n\nMake sure you have docker buildx on your system.\n\n```sh\ncd docker/sds-api/spine-directory-service/sds\npython3 -m venv .venv\npipenv install\nYou need to have pem and key files under data/certs, you may need to run a local copy to get these.\ncd ../..\nexport BUILD_TAG='latest'\n./buildx.sh\n```\n\nConnect to the VPN,\n\nYou may have issues with the container connecting via the VPN. If so please look at the answer given here \u003chttps://superuser.com/questions/1579858/docker-bridge-network-sporadically-loosing-packets/1580017?_gl=1*wyte41*_ga*MjgwODQyNzEwLjE3MDYwMDMwNzQ.*_ga_S812YQPLT2*MTcwNjE5MjIyOC4yLjAuMTcwNjE5MjIyOC4wLjAuMA..#1580017\u003e using `docker network create --subnet=172.20.0.0/24 --gateway=172.20.0.1 docker20`\n\nFinally run\n\n```sh\ndocker-compose up\n```\n\n#### Updating hooks\n\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 is useful to run them locally too.\n\n```\nmake install-hooks\n```\n\n### Environment Variables\n\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\n\nThere are `make` commands that alias some of this functionality:\n\n* `lint` -- Lints the spec and code\n* `publish` -- Outputs the specification as a **single file** into the `build/` directory\n* `serve` -- Serves a preview of the specification in human-readable format\n\n### Testing\n\nEach API and team is unique. We encourage you to use a `test/` folder in the root of the project, and use whatever testing frameworks or apps your team feels comfortable with. It is important that the URL your test points to be configurable. We have included some stubs in the Makefile for running tests.\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\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### Speccy\n\n\u003e [Speccy](http://speccy.io/) *A handy toolkit for OpenAPI, with a linter to enforce quality rules, documentation rendering, and resolution.*\n\nSpeccy does the lifting for the following npm scripts:\n\n* `test` -- Lints the definition\n* `publish` -- Outputs the specification as a **single file** into the `build/` 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\n\nSwagger UI unfortunately doesn't correctly render `$ref`s in examples, so use `speccy serve` instead.\n\n#### Apigee Portal\n\nThe Apigee portal will not automatically pull examples from schemas, you must specify them manually.\n\n## Deployment\n\n### Specification\n\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\n\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. A *Target Server* named `spine-directory-target`\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\n### Sandbox\n\nSandbox environment mimics real service behaviour - both correct HTTP 200 and client error responses 4xx codes.\nBoth /Endpoint and /Device has built in one response with data that can be fetched using query parameters specified below. All other combinations result with empty FHIR bundle simulating no result found.\n\n1. `/Endpoint`\n* `organization=https://fhir.nhs.uk/Id/ods-organization-code|YES`\n* `identifier=https://fhir.nhs.uk/Id/nhsEndpointServiceId|urn:nhs:names:services:psis:REPC_IN150016UK05`\n* `identifier=https://fhir.nhs.uk/Id/nhsMhsPartyKey|YES-0000806`\n\nQuery parametere `organization` is mandatory. At least one `identifier` must be present.\n\nExample: `/Endpoint?organization=https://fhir.nhs.uk/Id/ods-organization-code|YES\u0026identifier=https://fhir.nhs.uk/Id/nhsEndpointServiceId|urn:nhs:names:services:psis:REPC_IN150016UK05\u0026identifier=https://fhir.nhs.uk/Id/nhsMhsPartyKey|YES-0000806`\n\n2. `/Device`\n* `organization=https://fhir.nhs.uk/Id/ods-organization-code|YES`\n* `identifier=https://fhir.nhs.uk/Id/nhsEndpointServiceId|urn:nhs:names:services:psis:REPC_IN150016UK05`\n* `identifier=https://fhir.nhs.uk/Id/nhsMhsPartyKey|YES-0000806`\n* `manufacturing-organization=https://fhir.nhs.uk/Id/ods-organization-code|YES`\n\nQuery parameters `organization` and `identifier(https://fhir.nhs.uk/Id/nhsEndpointServiceId)` are mandatory. One or both `identifier(https://fhir.nhs.uk/Id/nhsMhsPartyKey)` and `manufacturing-organization` can be supplied.\n\nExample: `/Device?organization=https://fhir.nhs.uk/Id/ods-organization-code|YES\u0026identifier=https://fhir.nhs.uk/Id/nhsEndpointServiceId|urn:nhs:names:services:psis:REPC_IN150016UK05\u0026identifier=https://fhir.nhs.uk/Id/nhsMhsPartyKey|YES-0000806\u0026manufacturing-organization=https://fhir.nhs.uk/Id/ods-organization-code|YES`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnhsdigital%2Fspine-directory-service-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnhsdigital%2Fspine-directory-service-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnhsdigital%2Fspine-directory-service-api/lists"}