README.md

NHS Notify Supplier API

The NHS Notify Supplier API is intended primarily for print suppliers to integrate with the NHS Notify message request queueing system.

It models the concepts needed to configure production of letters and other printed materials to specific specifications, provide proofs of these materials, receive batch production requests, provide details of returned letters and correspondence, and to report on the status of these artifacts and associated management information such as volumes and assocated costs.

This repository documents the Supplier API specification and provides an SDK with examples and reference client implementations for interacting with it.

OAS Specifications

• Current Version

Table of Contents

• NHS Notify Supplier API
• OAS Specifications
• Table of Contents
• API Consumers - Getting Started
  • OAS Specification
  • Packages
  • Documentation
  • SDK Assets
  • Examples
• API Developers
  • Documentation
  • pre built servers
  • Setup
    • Prerequisites and Configuration
      • SDKs
      • Servers
      • Libs
  • Build
  • GitHub Actions CI/CD
    • CI (Automatic)
    • CD (Manual)
• Licence

API Consumers - Getting Started

OAS Specification

• Download the OAS Specification File from the latest releases
  • OAS JSON files api-oas-specification-[Version].zip

Packages

• NPM package

Documentation

• View the latest SDK documentation
• Download local versions of the API docs from the latest releases
  • HTML sdk-html-[Version].zip
  • Swagger sdk-swagger-[Version].zip

SDK Assets

If packages are unavailable the latest SDKs can be downloaded directly from:

• Download SDKs from the latest releases
  • Python sdk-python-[Version].zip
  • TypeScript sdk-ts-[Version].zip
  • CSharp sdk-csharp-[Version].zip

Examples

TODO:CCM-11209 Links to example clients.

API Developers

New developer of the NHS Notify Supplier API should understand the below.

Documentation

• Built
• Source

pre built servers

• "Working" C# server /src/server/host docker run -p 8080:8080 ghcr.io/nhsdigital/libshostdocker:latest
  • View at http://localhost:8080/swagger/index.html
• Docker OAS example Server (csharp) docker run -p 3000:3000 ghcr.io/nhsdigital/nhsnotifysupplierserver:latest
• CSharp server-csharp-[Version].zip

Setup

Prerequisites and Configuration

• Utilised the devcontainer, for pre reqs and configuration.
• You should open in a devcontainer or a Github workspaces.
• By default it will run make config when the container is first setup

SDKs

• The SDK folder is excluded from all pre reqs
• DO NOT make manual changes to the SDK, instead build it
• The SDK folder is excluded from git commits, and will be built as part of the CI/CD pipeline and released as a GitHub release.

Servers

• Servers folder is being built at build time from OAS specs.
• TODO:CCM-12139 Build actual servers

Libs

• /src/server has various separate libaries that are used by:
  • /src/server/host custom loads libs for different parts of the server

Build

To generate the SDK folder from changes to the specification/api/notify-supplier.yml OAS specification:

make clean
make build

This will generate:

• Python SDK
• TypeScript SDK
• HTML Docs

To view HTML docs:

make serve

by default they will be available at http://localhost:3050

These are generated using https://hub.docker.com/r/openapitools/openapi-generator-cli

GitHub Actions CI/CD

CI (Automatic)

PRs will run the CI workflow for testing.

PRs that are merged to main will run the same CI workflow will generate a pre-release based on the date and the commit hash.

CD (Manual)

Deployments can be made of any release (including the GitHub pages) by running the CD pipeline cicd-3-deploy.yaml

Licence

Unless stated otherwise, the codebase is released under the MIT License. This covers both the codebase and any sample code in the documentation.

Any HTML or Markdown documentation is © Crown Copyright and available under the terms of the Open Government Licence v3.0.