Use Case - API Consumer Gets Specific Relationship

User Story Summary (Clinical Overview) As an API Consumer (Proxy),
I want to be able to search using a Patient's NHS Number,
So that I can retrieve details of a Patient's relationships including provenance data.
Actors (Role) API Consumer (Proxy)
Frequency of Use Multiple times a day.
Triggers
  • API Consumer requests specific relationships for a patient.
Pre-conditions
  • API Consumer is authenticated.
  • API Consumer is authorised to view relationships.
  • Relationship ID or patient and related person IDs are provided.
  • Relationship exists in the system.
Post-conditions
  • Detailed information about the specific relationship is returned.
  • Complete provenance information is included.
Flow
  1. Proxy receives an online request for Proxy access.
  2. Proxy sends GET request to /RelatedPerson/id endpoint.
  3. System validates that the relationship ID exists.
  4. System retrieves relationship details including:
    • Relationship type (mother, father, etc.).
    • NHS Numbers of both people.
    • Names and demographic details.
    • Detailed provenance information.
    • Status (active, inactive, etc.).
    • Period of validity if applicable.
  5. System returns a complete RelatedPerson FHIR resource.
  6. Proxy uses information for processing Proxy Access.
Alternate Flow
  • When a unique match is not found for a parent, then the parent is not added as a RelatedPerson on the child's record.
Exception
  • Given that a child's record has a mother or father RelatedPerson with an NHS number,
  • When a parent match is found with a different NHS number,
  • Then the parent matched by RPN is not added to the child's record as a RelatedPerson,
  • And an NBO work item is raised.
  • If the relationship doesn't exist:
    • System returns a 404 Not Found error.
  • If either person 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 detailed information for the requested relationship.
  • System includes complete provenance information.
  • System provides appropriate error responses when relationships or people don't exist.
  • System supports querying by relationship ID or by patient and related person IDs.
  • 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.