NHS App

This is a RESTful HL7® FHIR® API specification for the NHS App API.

• 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 Apigee API Proxy definitions.

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

Requirements

• make
• nodejs + npm/yarn
• poetry
• Java 8+

Install

$ make install

Updating hooks

You can install some pre-commit hooks to ensure you can't commit invalid spec changes by accident. These are also run in CI, but it's useful to run them locally too.

$ make install-hooks

Environment Variables

Various scripts and commands rely on environment variables being set. These are documented with the commands.

💡 Consider using direnv 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.

Make commands

There are make commands that alias some of this functionality:

• lint -- Lints the spec and code
• publish -- Outputs the specification as a single file into the build/ directory
• serve -- Serves a preview of the specification in human-readable format

Testing

The tests/ folder contains some .NET integration tests to verify that the API endpoints can be successfully exercised when presented with valid authentication headers.

VS Code Plugins

• openapi-lint resolves links and validates entire spec with the 'OpenAPI Resolve and Validate' command
• OpenAPI (Swagger) Editor provides sidebar navigation

Emacs Plugins

• openapi-yaml-mode provides syntax highlighting, completion, and path help

Speccy

Speccy A handy toolkit for OpenAPI, with a linter to enforce quality rules, documentation rendering, and resolution.

Speccy Generator does the lifting for the following npm scripts:

• publish -- Outputs the specification as a single file into the dist/ directory
• lint -- Lints the definition
• serve -- Serves a preview of the specification in human-readable format
  • Please note, serve requires port 5000 to be available. Thus, in the case of macOS users, please disable the 'AirPlay Receiver' beforehand.

(Workflow detailed in a post on the developerjack blog.)

💡 The publish command is useful when uploading to Apigee which requires the spec as a single file.

Caveats

Swagger UI

Swagger UI unfortunately doesn't correctly render $refs in examples, so use speccy serve instead.

Apigee Portal

The Apigee portal will not automatically pull examples from schemas, you must specify them manually.

Deployment

Specification

Update the API Specification and derived documentation in the Portal.

make deploy-spec with environment variables:

• APIGEE_USERNAME
• APIGEE_PASSWORD
• APIGEE_SPEC_ID
• APIGEE_PORTAL_API_ID

API Proxy & Sandbox Service

Redeploy the API Proxy and hosted Sandbox service.

make deploy-proxy with environment variables:

• APIGEE_USERNAME
• APIGEE_PASSWORD
• APIGEE_ORGANIZATION
• APIGEE_ENVIRONMENTS - Comma-separated list of environments to deploy to (e.g. test,prod)
• APIGEE_APIPROXY - Name of the API Proxy for deployment
• APIGEE_BASE_PATH - The proxy's base path (must be unique)

💡 Specify your own API Proxy (with base path) for use during development.

Platform setup

Successful deployment of the API Proxy requires:

1. A Target Server named nhs-app-target
2. A Key-Value Map named nhsa-variables, containing any values you might need at proxy runtime
3. A Key-Value Map named nhsa-variables-encrypted, containing any secrets you might need at proxy runtime

💡 For Sandbox-running environments (test) these need to be present for successful deployment but can be set to empty/dummy values.