NPA-6402: Initial Commit

[ChristopherBacon]

Description/Summary of Changes

Pull Request

🧾 Ticket Link

https://nhsd-jira.digital.nhs.uk/browse/NPA-6402

This PR updates the sandbox API, OAS specification, example YAML responses, Postman collections, and tests to replace _include=Consent:performer with _include=Consent:grantee. When _include=Consent:grantee is used, the response now returns a Patient resource for the proxy (containing their demographic information) and a RelatedPerson resource for the relationship, rather than only returning a RelatedPerson resource for the proxy as was previously the case with Consent:performer.

This change addresses the issue where Proxy Role Related Persons may not exist in PDS (e.g. when a GP sets up a proxy role via NPS for a carer). By returning proxy details via a Patient resource, VRS avoids the scenario where PDS returns a 404 for a non-existent RelatedPerson, which would previously cause VRS to return an error.

• Renamed _include parameter value from Consent:performer to Consent:grantee across the sandbox API code (constants.py, utils.py, get_consent.py, get_consent_by_id.py)
• Updated all YAML example response files in both sandbox/api/examples/ and specification/examples/responses/ to reflect the new Consent:grantee include behaviour, with grantee includes now returning a Patient resource for the proxy and a RelatedPerson resource for the relationship
• Renamed example files from *-include-performer* to *-include-grantee* naming convention
• Removed old Consent:performer example files that are no longer needed
• Updated the OAS specification (validated-relationships-service-api.yaml) to document Consent:grantee as the valid include parameter value, including descriptions, scenario tables, example references, and enum definitions
• Updated both Postman collections (sandbox and integration) to use Consent:grantee in place of Consent:performer
• Updated all sandbox unit tests to use Consent:grantee parameter values and reference the renamed example files

---

Developer Testing Carried Out

• All 103 sandbox unit tests pass (cd sandbox && python -m pytest api/tests/ -v)
• Tests cover both GET /Consent and GET /Consent/{id} endpoints with _include=Consent:grantee, _include=Consent:patient, and both combined
• Tests verify correct example YAML files are returned for each combination of query parameters including performer:identifier, patient:identifier, and _include params
• Tests cover error scenarios (invalid include params returning 422, internal server errors)
• Verified YAML example responses contain the correct resource types: Consent (match), Patient for proxy (include), RelatedPerson for relationship (include), and Patient for patient (include)

---

Reviewer Testing Required

• Clone the branch and run sandbox tests: cd sandbox && python -m pytest api/tests/ -v - all 103 tests should pass
• Start the sandbox locally and verify the following scenarios against the OAS spec scenario tables:
  • GET /Consent?performer:identifier=9000000010&_include=Consent:grantee returns a Bundle with the Consent resource and a Patient resource for the proxy
  • GET /Consent?performer:identifier=9000000010&_include=Consent:grantee&_include=Consent:patient returns a Bundle with the Consent, Patient (proxy), RelatedPerson (relationship), and Patient (patient) resources
  • GET /Consent/{id}?_include=Consent:grantee returns the expected included resources for both consenting adult (74eed847-ca25-4e76-8cf2-f2c2d7842a7a) and mother-child (39df03a2-1b14-4d19-b1dc-d5d8cbf96948) scenarios
  • GET /Consent?performer:identifier=9000000022&_include=Consent:grantee returns multiple relationships with proxy Patient resources included
  • Invalid _include values (e.g. _include=Consent:performer) return HTTP 422 with an INVALID_PARAMETER error
• Import the updated Postman sandbox collection and verify requests using Consent:grantee return expected responses
• Review the OAS specification renders correctly and the scenario tables, parameter enums, and example references all reflect Consent:grantee

---

✅ Developer Checklist

• PR title follows the format: NPA-XXXX: <short-description>
• Branch name follows the convention: <type>/NPA-XXXX/<short-description>
• Commit messages follow the template: NPA-XXXX: <short-description>
• All acceptance criteria from the Jira ticket are addressed
• Automated tests (unit/integration/API/infrastructure etc. tests) are added or updated
• Assignees and appropriate labels (e.g. terraform, documentation) are added

---

👀 Reviewer Checklist

• Changes meet the acceptance criteria of the Jira ticket
• Code is able to be merged (no conflicts and adheres to coding standards)
• Sufficient test evidence is provided (manual and/or automated)
• Infrastructure/operational/build changes are validated (if applicable)

---

🚀 Post-merge

After merging and deploying changes to the sandbox, Postman collection or spec examples please run the Run Postman
collection workflow.

This will run the tests within the collection to check that the sandbox is working as expected once deployed.

[github-actions]

This branch is work on a ticket in the NHS Digital NPA JIRA Project. Here's a handy link to the ticket:

NPA-6402

[github-actions]

This branch is work on a ticket in the NHS Digital NPA JIRA Project. Here's a handy link to the ticket:

NPA-6402

[github-actions]

This branch is work on a ticket in the NHS Digital NPA JIRA Project. Here's a handy link to the ticket:

NPA-6402

[ClarksonAdam]

Couple of small things to resolve. Otherwise it's looking good

[github-actions]

This branch is work on a ticket in the NHS Digital NPA JIRA Project. Here's a handy link to the ticket:

NPA-6402

[ClarksonAdam]

LGTM 👍