VED-940 Restructure Search API Sections

[JamesW1-NHS]

Summary

• Routine Change

Update the OAS documentation for Search to improve clarity and separate GET and POST into distinct, consistent sections.

Changes required:

Rename GET title to "Search for a patient’s immunisation records (GET)".
Reduce and tidy GET text; move generic content (e.g. Flagged Patients) to a general section near the top.
Remove details no longer needed (NHS number change, location text, duplicate contained-resource note).
Create a new dedicated section for Search POST titled “Search for a patient’s immunisation records (POST)”.
Explain purpose of POST and how it differs from GET.
Link POST to the GET section for shared details to avoid duplication.
Remove search by identifier from OAS file. May have to be reinserted in the future based on user requirements (GPIT)

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 of the acceptance criteria of the ticket.
• If there were infrastructure, operational, or build changes, I have made sure there is sufficient evidence that the changes will work.
• If there were changes that are outside of the regular release processes e.g. account infrastructure to setup, manual setup for external API integrations, secrets to set, then I have checked that the developer has flagged this to the Tech Lead as release steps.
• I have checked that no Personal Identifiable Data (PID) is logged as part of the changes.

[github-actions]

This branch is working on a ticket in the NHS England VED JIRA Project. Here's a handy link to the ticket:

VED-940

[dlzhry2nhs]

Couple of general comments but overall looks good. One or two may need clarifying with PO/Architect as am not 100% clear on exactly what they are expecting from some of the bullet points.

[dlzhry2nhs]

When testing with the sandbox, it is telling me that: Violation: response.body.entry.0.resource Response body property entry.0.resource must match exactly one schema in oneOf.

This means that the first object in the example, the immunization, does not conform to the spec we've written. It could be the bit to do with search mode. Worth double checking exactly what it is that is upsetting it.

[dlzhry2nhs]

The first places I would look is the structure of the patient object in the immunization as we mess around with this in search. Secondly, the example also contains a "search": {
"mode": "match"
} object, so also worth a check.

[JamesW1-NHS]

This is VED-298. I'll be looking at it in due course.
The important thing is that the current changes (indeed all the changes since the original JSON) don't appear to have broken the sandbox any more than it was to start with.)

[dlzhry2nhs]

Right, I would say the structure of the API response schema vs. example fundamentally does not match, so while we are working on adding the documentation for the POST endpoint this would be an ideal time to ensure things are right.

If we are not publishing until after VED-298 then it's ok to defer, but I would prefer when we introduce a new endpoint to the OAS file then it is completed properly rather than in a partially complete state.

[dlzhry2nhs]

Would ideally like the new endpoint example to match its schema, but worst case scenario can look to resolve in the next ticket.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud