CMSNAV-747: Update OAS Specification for Content API

.devcontainer/devcontainer.json

@@ -0,0 +1,31 @@
+// For format details, see https://aka.ms/devcontainer.json. For config options, see the
+// README at: https://github.com/devcontainers/templates/tree/main/src/python
+{
+	"name": "Python 3",
+	// Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile
+	"image": "mcr.microsoft.com/devcontainers/python:1-3.10-bullseye",
+	"features": {
+		"ghcr.io/devcontainers/features/node:1": {
+			"nodeGypDependencies": true,
+			"installYarnUsingApt": true,
+			"version": "lts",
+			"pnpmVersion": "latest",
+			"nvmVersion": "latest"
+		}
+	},
+
+	// Features to add to the dev container. More info: https://containers.dev/features.
+	// "features": {},
+
+	// Use 'forwardPorts' to make a list of ports inside the container available locally.
+	 "forwardPorts": [5000, 32201],
+
+	// Use 'postCreateCommand' to run commands after the container is created.
+	"postCreateCommand": "./.devcontainer/postCreateCommand.sh"
+
+	// Configure tool-specific properties.
+	// "customizations": {},
+
+	// Uncomment to connect as root instead. More info: https://aka.ms/dev-containers-non-root.
+	// "remoteUser": "root"
+}

.devcontainer/postCreateCommand.sh

@@ -0,0 +1,15 @@
+#!/bin/bash
+
+# Install JVM
+
+sudo apt update
+sudo apt install -y default-jdk
+
+# Install poetry
+
+#!/bin/bash
+curl -sSL https://install.python-poetry.org | python3 -
+echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
+
+make install
+echo "..Now you can 'make lint', 'make publish', 'npm run serve'"

.github/dependabot.yml

@@ -0,0 +1,12 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for more information:
+# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
+# https://containers.dev/guide/dependabot
+
+version: 2
+updates:
+ - package-ecosystem: "devcontainers"
+   directory: "/"
+   schedule:
+     interval: weekly

Makefile

@@ -12,6 +12,7 @@ install-node:
 #Configures Git Hooks, which are scripts that run given a specified event.
 .git/hooks/pre-commit:
 	cp scripts/pre-commit .git/hooks/pre-commit
+	chmod +x .git/hooks/pre-commit
 
 #Condensed Target to run all targets above.
 install: install-node install-python .git/hooks/pre-commit
@@ -31,6 +32,10 @@ publish: clean
 	mkdir -p build
 	npm run publish 2> /dev/null
 
+#Serve the API description locally
+serve:
+	npm run serve
+
 #Runs build proxy script
 build-proxy:
 	scripts/build_proxy.sh

README.md

@@ -21,18 +21,31 @@ The contents of this repository are protected by Crown Copyright (C).
 
 ## Development
 
-### Requirements
+You can set up your development manually on your development machine, or :bulb: use the supplied devcontainer specification to set up
+the required environment automatically.
+
+### :bulb: Developing in a devcontainer
+
+If you are unfamiliar with the use of devcontainers, these resources may be helpful:
+- VSCode: https://code.visualstudio.com/docs/devcontainers/tutorial
+- JetBrains/pycharm: https://www.jetbrains.com/help/idea/prerequisites-for-dev-containers.html 
+
+The provided configuration in the .devcontainer folder will set up all the required tooling as detailed in the following section automatically.
+
+### Developing without a devcontainer
+
+#### Requirements
 * make
 * nodejs + npm/yarn
 * [poetry](https://github.com/python-poetry/poetry)
 * Java 8+
 
-### Install
+#### Install
 ```
 $ make install
 ```
 
-#### Updating hooks
+##### 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.
 
@@ -49,7 +62,7 @@ Various scripts and commands rely on environment variables being set. These are
 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
+ * `serve` -- Serves a preview of the specification in human-readable format on http://127.0.0.1:5000
 
 ### Testing
 Each 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.

azure/api_development.md

@@ -0,0 +1,75 @@
+# NHS Website Content API Update and Release Process
+
+This document outlines the steps involved in updating the NHS Website Content API, from making code changes to deploying them to production.
+
+## 1. Prerequisites and Setup
+
+*   **Development Environment:**
+    *   Use the provided VSCode Dev Container for an automated setup.
+    *   Alternatively, manually install `make`, NodeJS (`npm`), Python (`poetry`), and Java 8+.
+*   **Install Dependencies:** Run `make install` in the project root directory. This installs both Node and Python dependencies.
+*   **Install Git Hooks:** Run `make install-hooks` to set up pre-commit hooks that help prevent committing invalid changes.
+*   **Environment Variables:** Configure necessary environment variables (e.g., for API keys, tokens). Using `direnv` with a local `.envrc` file is recommended.
+
+## 2. Making Changes
+
+*   **Create a Branch:** Create a new feature branch from the `master` branch. Follow the naming convention: `apm-nnn-short-issue-description` (where `apm-nnn` is the relevant Jira ticket number).
+*   **Implement Changes:** Modify the necessary files:
+    *   **API Specification:** Edit files within the `specification/` directory (primarily `nhs-website-content-api.yaml` and files in `specification/components/`).
+    *   **Sandbox Implementation:** Update the NodeJS sandbox application in the `sandbox/` directory if required.
+    *   **Apigee Proxies:** Modify proxy definitions in `proxies/live/` or `proxies/sandbox/`.
+    *   **Tests:** Add or update tests in the `tests/` directory.
+    *   **Scripts/Tooling:** Update files in `scripts/` or the `Makefile` if necessary.
+*   **Commit Changes:** Commit your work frequently with clear messages following the format:
+    ```
+    APM-NNN Summary of changes
+
+    Longer description of changes if explaining rationale is necessary...
+    ```
+
+## 3. Local Validation
+
+*   **Linting:** Run `make lint` to check code style and specification validity. The pre-commit hooks should also run linters automatically.
+*   **Build Specification:** Run `make publish` to bundle the OpenAPI specification into a single file in the `build/` directory. This helps catch resolution errors.
+*   **Preview Specification:** Run `make serve` to view a human-readable version of the specification locally at `http://127.0.0.1:5000`.
+*   **Local Testing (Conceptual):** While the `Makefile` includes targets like `make test`, running these directly in the VSCode terminal might not work as the full execution context (like dependent services) exists within deployed containers. These tests are primarily designed to be run within the CI/CD pipeline. If manual testing against a locally running sandbox (via Docker) is needed, you would typically use `docker compose exec` to run commands like `pytest` within the appropriate container.
+
+## 4. Pull Request and Code Review
+
+*   **Push Branch:** Push your feature branch to the GitHub repository.
+*   **Create Pull Request (PR):** Open a PR from your feature branch targeting the `master` branch.
+    *   Ensure the PR title and description are clear and link to the relevant Jira ticket (APM-NNN).
+*   **Automated Checks:** The PR will trigger automated workflows (defined in `.github/workflows/` and `azure/azure-pr-pipeline.yml`):
+    *   Linting checks.
+    *   Deployment of an ephemeral version of the API (including specification, proxy, and sandbox container) to a development environment (e.g., `internal-dev`) for testing.
+*   **Code Review:** Team members review the code changes, specification updates, and test results from the ephemeral deployment.
+*   **Approval:** Once the PR is approved and all checks pass, it's ready for merging.
+
+## 5. Merging
+
+*   **Merge:** The *reviewer* who approved the PR is responsible for merging it into the `master` branch.
+
+## 6. CI/CD Pipeline (Azure DevOps)
+
+*   **Trigger:** Merging to `master` automatically triggers the main Azure DevOps pipelines (`azure-build-pipeline.yml`, `azure-release-pipeline.yml`).
+*   **Build (`azure-build-pipeline.yml`):**
+    *   Builds the consolidated OpenAPI specification (`make publish`).
+    *   Builds the Apigee proxy bundles (`make build-proxy`).
+    *   Builds any necessary Docker images (e.g., the sandbox defined in `sandbox/Dockerfile` and configured in `ecs-proxies-containers.yml`).
+    *   Pushes Docker images to the container registry.
+    *   Packages build artifacts (spec, proxies, test files, config like `manifest_template.yml`, `ecs-proxies-deploy.yml`) for deployment.
+*   **Release (`azure-release-pipeline.yml`):**
+    *   Deploys the artifacts and containers sequentially to configured environments (e.g., Internal Dev -> Internal QA -> Production).
+    *   Deployment includes:
+        *   Apigee Proxies (Live and Sandbox).
+        *   Updated API Specification to the Apigee Developer Portal.
+        *   Deployment/Update of backend containers (like the Sandbox) on ECS, configured via `ecs-proxies-deploy.yml`.
+    *   Runs automated tests (smoke tests, integration tests defined in `tests/` and executed via `Makefile` targets like `smoketest` or `test`) against each environment after deployment (`azure/templates/run-tests.yml`).
+
+## 7. Production Release
+
+*   **Promotion:** After successful deployment and testing in pre-production environments (e.g., Internal QA), the release pipeline promotes the changes to the Production environment.
+*   **Post-Release Checks:** Smoke tests (`make smoketest-prod`) are typically run against the production environment to verify the deployment.
+*   **GitHub Release:** A GitHub release is automatically created/updated upon merging to `master` (driven by `.github/workflows/continuous-integration.yml`).
+
+This process ensures that changes are validated, tested, and deployed systematically across environments.