APIM Cut 1.54

[EdwardWills-nhs]

Summary

• Routine Change
• ❗ Breaking Change
• 🤖 Operational or Infrastructure Change
• ✨ New Feature
• ⚠️ Potential issues that might be caused by this change

Add any other relevant notes or explanations here. Remove this line if you have nothing to add.

Reviews Required

• Dev
• Test
• Tech Author
• Product Owner

Review Checklist

ℹ️ This section is to be filled in by the reviewer.

• I have reviewed the changes in this PR and they fill all or part of the acceptance criteria of the ticket, and the code is in a mergeable state.
• If there were infrastructure, operational, or build changes, I have made sure there is sufficient evidence that the changes will work.
• I have ensured the changelog has been updated by the submitter, if necessary.

[Copilot]

Pull request overview

This PR looks like an “APIM cut” that updates API specification/behaviour (notably attachment retrieval error handling), refreshes dependency/tooling versions, and extends deployment/ops configuration (new environment + pipeline stage), alongside adding internal repo guidance prompts/instructions.

Changes:

• Update attachment retrieval semantics/documentation for FHIR R4 to return 422 Unprocessable Entity when an attachment is not yet downloadable, including new OperationOutcome example.
• Refactor STU3 upload/download content-type schemas (inline media types) and update sandbox mappings/mocks accordingly.
• Update dependency/tooling configuration (Redocly CLI, Python deps) and CI/CD/pipeline wiring (new testdev internal-dev deployment stage), plus add repo “Copilot context” and instruction/prompt docs.

Reviewed changes

Copilot reviewed 30 out of 33 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
tests/integration/test_user_restricted.py	Simplifies the user-restricted integration tests and removes negative-path cases.
tests/data.py	Updates the Actor.RC user ID used in integration/auth flows.
tests/conftest.py	Removes apim_app_flow_vars fixture usage and updates app-restricted user ID.
specification/components/stu3/schemas/responses/retrieveAttachment/200Response.yaml	Expands 200 response content to explicit media types using StringBinarySchema.
specification/components/stu3/schemas/file/FileContentTypeSchemaUpload.yaml	Removes the shared upload content-type schema file.
specification/components/stu3/schemas/file/FileContentTypeSchemaDownload.yaml	Removes the shared download content-type schema file.
specification/components/stu3/schemas/endpoints/a020-upload-file-to-document-store.yaml	Inlines requestBody media types instead of $ref to removed schema file.
specification/components/r4/schemas/responses/retrieveAttachment/422Response.yaml	Adds a new documented 422 OperationOutcome response for attachment retrieval.
specification/components/r4/schemas/endpoints/a042-retrieve-attachment.yaml	Updates docs + adds 422 response reference for attachment availability errors.
sandbox/src/routes/stu3/services/mockResponseProvider.js	Adds new request→response mappings for cancel referral scenarios.
sandbox/src/mocks/r4/NHSDigital-OperationOutcome-422.json	Adds sandbox mock example used by the spec examples pipeline.
sandbox/python-deps.txt	Adds a Python dependency snapshot file (appears generated).
sandbox/package.json	Bumps globals devDependency.
sandbox/package-lock.json	Updates lockfile to v3 and refreshes transitive deps.
redocly.yaml	Updates Redocly rule configuration (stops disabling info-license-url).
pyproject.toml	Updates Python dependency versions (incl. openapi-core, pytest, pytest-nhsd-apim) and adds werkzeug constraint.
package.json	Upgrades @redocly/cli to v2 and adds handlebars override.
node-deps.json	Adds a Node dependency tree/snapshot file (appears generated).
manifest_template.yml	Adds testdev-internal-dev Apigee environment entry.
azure/azure-release-pipeline.yml	Adds testdev release stage and manual approval gate.
.github/workflows/continous-integration-workflow.yaml	Pins GitHub Actions to specific SHAs.
.github/workflows/combine-prs.yml	Pins actions/github-script to a specific SHA.
.github/prompts/release.prompt.md	Adds a release-process Copilot prompt.
.github/prompts/overview.prompt.md	Adds a repo overview/onboarding Copilot prompt.
.github/prompts/add-context.prompt.md	Adds a Copilot prompt for updating .github/copilot-instructions.md.
.github/instructions/testing.instructions.md	Adds test-suite conventions and guidance.
.github/instructions/specification.instructions.md	Adds OAS workflow + examples pipeline documentation.
.github/instructions/sandbox.instructions.md	Adds sandbox architecture + patterns documentation.
.github/instructions/proxy.instructions.md	Adds Apigee proxy architecture + flow documentation.
.github/copilot-instructions.md	Adds repo-wide Copilot context (structure, workflows, conventions).
.github/CODEOWNERS	Adds an additional code owner for dependency/version files.

Files not reviewed (1)

• sandbox/package-lock.json: Language not supported

Comments suppressed due to low confidence (1)

redocly.yaml:7

• redocly.yaml no longer disables the info-license-url rule, but the OpenAPI spec only provides info.license.name (no info.license.url). With the recommended ruleset this will cause make lint / redocly lint to fail unless the spec is updated.

Either re-disable the rule here, or add a license URL to specification/e-referrals-service-api.yaml.

extends:
  - recommended
rules:
  no-invalid-media-type-examples:
    severity: off
  tag-description: off

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[georgeCraftReferrals]

lgtm