prescriptions-for-patients

This is a proxy code and specification for the prescriptions-for-patients API.
This calls an AWS API that is defined at https://github.com/NHSDigital/prescriptionsforpatients.
The API returns prescriptions for the NHS number that the caller is authenticated with. In non production environments you can pass in a header called x-nhs-number to get details for an NHS number other than the one you are authenticated with.
Access to the API is restricted to authenticated NHS login OAuth V2 token.

• specification/ This Open API Specification describes the endpoints, methods and messages exchanged by the API. Use it to generate interactive documentation; the contract between the API and its consumers.
• scripts/ Utilities helpful to developers of this specification.
• proxies/ Live (connects to the AWS ci deployment) and sandbox (connects to the AWS sandbox deployment) Apigee API Proxy definitions.
• .github/ Contains issue template and github workflows
• azure/ Contains azure pipeline definitions for builds and releases

• .devcontainer Contains a dockerfile and vscode devcontainer definition

Consumers of the API will find developer documentation on the NHS Digital Developer Hub.

Contributing

Contributions to this project are welcome from anyone, providing that they conform to the guidelines for contribution and the community code of conduct.

Licensing

This 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.

The contents of this repository are protected by Crown Copyright (C).

Development

It is recommended that you use visual studio code and a devcontainer as this will install all necessary components and correct versions of tools and languages.
See https://code.visualstudio.com/docs/devcontainers/containers for details on how to set this up on your host machine.

All commits must be made using signed commits

Once the steps at the link above have been completed. Add to your ~/.gnupg/gpg.conf as below:

use-agent
pinentry-mode loopback

and to your ~/.gnupg/gpg-agent.conf as below:

allow-loopback-pinentry

As described here: https://stackoverflow.com/a/59170001

You will need to create the files, if they do not already exist. This will ensure that your VSCode bash terminal prompts you for your GPG key password.

You can cache the gpg key passphrase by following instructions at https://superuser.com/questions/624343/keep-gnupg-credentials-cached-for-entire-user-session

Pre-commit hooks

Some pre-commit hooks are installed as part of the install above to ensure you can't commit invalid spec changes by accident and to run basic lint checks. The pre-commit hook uses python package pre-commit and is configured in the file .pre-commit-config.yaml. A combination of these checks are also run in CI.

Make commands

There are the make targets defined:

• install -- Installs node and python dependencies and git pre-commit hook
• lint -- Lints the spec and code
• clean -- Removes files generated by build and testing runs
• deep-clean -- Removes installed node and python packages
• publish -- Outputs the specification as a single file into the build/ directory. This is used when uploading to Apigee, which requires the spec as a single file.
• build-proxy -- Used in CI to copy files to correct location for deployment
• smoketest -- runs tests marked as smoke test against non prod environment
• test -- runs all tests against non prod environment
• smoketest-prod -- runs tests marked as smoke test against prod environment
• test-prod -- runs all tests against prod environment
• check-licenses -- checks python and node dependencies for GPL licensed code
• publish-pfp-apigee* -- calls release notes lambda to create release notes in confluence
• mark-jira-released -- calls mark jira released lambda to mark jira release as released

Testing

There are some basic end to end tests that run as part of the CI build. These just test _ping and _status and Bundle endpoint are working as expected.
To set up variables to run these tests from your machine use the following. You will be asked for your Apigee credentials that you use to log onto Apigee management web page

export APIGEE_ACCESS_TOKEN=`SSO_LOGIN_URL=https://login.apigee.com get_token`
export PROXY_NAME=prescriptions-for-patients-internal-dev

For testing a pull request you can set PROXY_NAME

export PROXY_NAME=prescriptions-for-patients-pr-<GITHUB PULL REQUEST ID>

You also need to set environment variable SOURCE_COMMIT_ID to the full commit id of the deployed proxy. You can get this using git log .

Now you can then run the tests using the following

make test

For more information about testing your API see the API Producer Zone confluence.

/.github:

This folder contains workflows and templates related to github

• pull_request_template.yml: Template for pull requests.

/.github/workflows: This folder contains templates for github action workflows such as:

• pr-link.yaml: This workflow template links Pull Requests to Jira tickets and runs when a pull request is opened.
• continuous-integration.yml: This workflow template publishes a Github release when merged to master.
• dependabot.yml: Dependabot definition file
• combine-dependabot-prs.yml: Workflow for combining dependabot pull requests
• create_int_release_notes.yml: Workflow for creating int release notes. Called from azure pipeline
• create_prod_release_notes.yml: Workflow for creating prod release notes. Called from azure pipeline
• create_rc_int_release_notes.yml: Workflow for creating RC int release notes. Called from azure pipeline
• mark_jira_released.yml: Workflow for marking jira release as released. Called from azure pipeline

/azure:

Contains templates defining Azure Devops pipelines. By default the following pipelines are available:

• azure-build-pipeline.yml: Assembles the contents of the repository into a single file ("artifact") on Azure Devops. By default this pipeline is enabled for all branches.
• azure-pr-pipeline.yml: Deploys ephemeral versions of the proxy to Apigee to internal environments. You can run automated and manual tests against these while you develop. This pipeline will deploy to internal-dev, but the template can be amended to add other environments as required.
• azure-release-pipeline.yml: Deploys the long-lived version of your pipeline to internal and external environments, typically when you merge to master.

/azure/templates: Here you can define reusable actions, such as running tests, and call these actions during Azure Devops pipelines. 

/proxies:

This folder contains files relating to the Apigee API proxy.

There are 2 folders /live and /sandbox allowing you to define a different proxy for sandbox use. By default, this sandbox proxy is implemented to route to the sandbox target server

Within the live/apiproxy and sandbox/apiproxy folders are:

/proxies/default.xml: Defines the proxy's Flows. Flows define how the proxy should handle different requests. By default, _ping and _status endpoint flows are defined. See the APM confluence for more information on how the _ping and _status endpoints work.

/policies: Populated with a set of standard XML Apigee policies that can be used in flows.

/resources/jsc: Snippets of javascript code that are used in Apigee Javascript policies. For more info about Javascript policies see here

/targets: The XMLs within these folders set up target definitions which allow connections to external target servers. The sandbox target definition is implemented to route to the sandbox target server (code for this sandbox is found under /sandbox of this template repo). For more info on setting up a target server see the API Producer Zone confluence

/scripts:

Contains useful scripts that are used throughout the project, for example in Makefile and Github workflows

/specification:

The specification has been written to provide a clear representation of our API. Both what it expects and what it will return to the client. It conforms to the OpenAPI specification v3.0.x found here

For more information about developing specifications see the API Producer Zone confluence.

Usage

To view the specification in a user-friendly format, you will need VSCode with the OpenAPI extension (42Crunch.vscode-openapi) installed. Open the prescriptions-for-patients.yaml file and use the F1 > OpenAPI: show preview using ReDoc command.

manifest_template.yml:

This file defines 2 dictionaries of fields that are required for the Apigee deployment. For more info see the API Producer Zone confluence.

Package management:

This template uses poetry for python dependency management, and uses these files: poetry.lock, poetry.toml, pyproject.toml.

Node dependencies of this template project and some npm scripts are listed in: package.json, package-lock.json.