API Developers - Getting Started

2025-10-08 | 📑 500 words | ⏱ 5 mins | 🧾 History | ✍ NHS Notify | 🔑 NHS Notify

Known Issues / Todo

  • ⛅ This page is draft and is subject to rapid change, and may not be fully accurate or complete

Developers for the NHS Notify Supplier API should understand the following:

Repository Contents

The Supplier API repository contains the following:

  • .devcontainer - A devcontainer that should be used for work on this repository that maintains developer dependencies
  • .github - GitHub workflows and actions for CI/CD
  • docs - This documentation; generated and published on pre-release (PR merge to main)
  • infrastructure - Infrastructure as code maintained in Terraform
  • internal - Internal packages and libraries, e.g. database repositories
  • lambdas - Implementation of lambda handler functions
  • postman - Postman collection(s) which can be imported to assist in API development and testing
  • sandbox - Sandbox logic; [!NOTE] The sandbox specification is built from the core specification and should not be directly modified
  • scripts - Helpful tools for maintaining the project; e.g. includes implementation for commit hook checks and test data generation
  • server - Generated server implementation for the API; [!NOTE] Implementation is incomplete and these should not be used
  • specification - The location and build fragments for the API’s OAS file
  • src - Non lambda implementation
  • tests - Higher level component and E2E test suites

The API dependencies are managed through NPM Workspaces

Setup

Clone the repository

git clone https://github.com/NHSDigital/nhs-notify-supplier-api.git
cd nhs-notify-supplier-api
code .

Prerequisites & Configuration

devcontainer

You should use the devcontainer for this repository to satisy pre-requisites and configuration. You can open this using devcontainer plugins or GitHub workspaces By default it will run the necessary make config, postcreatecommand.sh, and poststartcommand.sh

Pre-requisites

The following software packages, or their equivalents, are expected to be installed and configured:

  • Docker container runtime or a compatible tool, e.g. Podman,
  • asdf version manager,
  • GNU make 3.82 or later,
  • GNU coreutils and GNU binutils may be required to build dependencies like Python, which may need to be compiled during installation. For macOS users, this has been scripted and automated by the dotfiles project; please see this script for details,
  • Python required to run Git hooks,
  • Ruby required for documentation builds,
  • jq a lightweight and flexible command-line JSON processor.

[!NOTE]
The version of GNU make available by default on macOS is earlier than 3.82. You will need to upgrade it or certain make tasks will fail. On macOS, you will need Homebrew installed, then to install make, like so:

brew install make

You will then see instructions to fix your $PATH variable to make the newly installed version available. If you are using dotfiles, this is all done for you.

Configuration

Installation and configuration of the toolchain dependencies (including pre-git hooks).

make config

Contributing

Refer to CONTRIBUTING for details about contributions to this repository