Use Case - API Consumer Gets All Related Persons

User Story Summary (Clinical Overview) As the National Proxy Service,
I want to retrieve all related persons for a specific patient,
So that I can display relationship information for clinical or administrative purposes.
Actors (Role) Proxy, Related Person Network (RPN)
Frequency of Use Multiple times a day.
Triggers
  • API Consumer requests all relationships for a patient.
Pre-conditions
  • API Consumer is authenticated.
  • API Consumer is authorised to view relationships.
  • Patient NHS number is valid.
  • Patient record exists in Neptune.
Post-conditions
  • All active related persons are returned for the specified patient.
  • Relationship provenance information is included for each relationship.
Flow
  1. API Consumer sends GET request to /RelatedPerson?patient:identifier endpoint.
  2. System validates the request parameters.
  3. System retrieves all active related persons from the RPN datastore.
  4. System returns a FHIR Bundle containing RelatedPerson resources.
  5. Each RelatedPerson resource includes:
    • Relationship type (mother, father, etc.).
    • NHS Number of the related person if available.
    • Name and demographic details.
    • Provenance information (source of relationship data).
    • Status (active, inactive, etc.).
Alternate Flow
  • If the patient has more related persons than the default page size:
    • Response includes links to retrieve next pages of results.
    • API Consumer can follow the links to retrieve all results.
Exception
  • If no related persons exist for the patient:
    • System returns an empty FHIR Bundle.
  • If the patient doesn't exist:
    • System returns a 404 Not Found error.
  • If the API Consumer does not have the appropriate permissions:
    • System returns a 403 Forbidden error.
Acceptance Criteria
  • System returns all active related persons for the requested patient.
  • System handles pagination appropriately for patients with many relationships.
  • System includes provenance information for each relationship.
  • System correctly indicates the origin of each relationship (GRO, PDS Riak, etc.).
  • Only authenticated API Consumers can access the API.
  • API Consumers can only access resources within their authorized scopes.
  • Authentication tokens expire after an appropriate period.
  • API properly enforces scope-based access control.
  • API properly supports multiple versions simultaneously.
  • API clearly indicates version information in responses.
  • API provides an appropriate warning period before version deprecation.
  • Documentation clearly explains differences between versions.
  • All API errors return appropriate HTTP status codes.
  • Error responses follow the FHIR OperationOutcome structure.
  • Error messages are clear, actionable, and user-friendly.
  • Each error includes a correlation ID for support reference.