kyle-mwnz
commented
6 months ago Hi @pat-ryan-health thanks for raising the suggestion - we will take a look
Closed pat-ryan-health closed 4 months ago
kyle-mwnz
commented
6 months ago Hi @pat-ryan-health thanks for raising the suggestion - we will take a look
mathusmith
commented
6 months ago There is a question as to whether the path needs to identify if an API is FHIR (and what FHIR version). My take is it does not unless there is FHIR and non-FHIR version of the API. The API spec/FHIR IG should inform on this, similarly the API version can cover API versions based on different FHIR versions.
pat-ryan-health
commented
6 months ago HIP has SOAP/FHIR and HL7v2 API for patient, so it is useful to be able to disnguish that in the namespace,
Also I think the version number is better placed after the resources since different resources change at different rates, so it is the resource which needs to be able to suppor tapth-based version rather than the product space
ChrisSquats
commented
6 months ago The URI page does provide a template for URI construction but as a change, suggest the following. I'd like feedback on cardinality choices and whether we see this as a MUST or SHOULD
| The table below represents the URI hierarchy APIs MUST use: | Level | Name | Cardinality |
|---|---|---|---|
| 1 | protocol\|standard |
0..1 | |
| 2 | protocol version |
Must be provided if protocol|standard is provided and relevant | |
| 3 | namespace |
0..1 | |
| 4 | version |
0..1 | |
| 5 | resource |
1..1 | |
| 6 | resource-id |
0..1 | |
| 7 | sub-resource |
0..1 | |
| 8 | sub-resource-id |
0..1 |
Examples:
[basePath]/fhir/r4b/nhi/v1/Patient/ZZZ008
[basePath]/fhir/r4b/air/v1/Immunization/_search
[basePath]/fhir/r4b/nzps/v1/Patient/$summary
[basePath]/contracts/v2/laboratories/33245/locations/P100782
[basePath]/v3/vaccinators/43265/certifications/7281
[basePath]/openid-connect/token
pat-ryan-health
commented
6 months ago Not sure about this " 2 protocol version Must be provided if protocol|standard is provided and relevant "
If we switched FHIR versions I would only want to change the endpoint if the new API was not backwards compatible with the old one. Everything the client needs to know about FHIR dependencies should be in the conformance artifacts, I don't see why we need to encode it in the URL. So I would drop that and add guidance on the
4 version 0..1
too say it should be used to differentiate between non-compatible versions of the API
From: ChrisSquats @.> Sent: Friday, May 3, 2024 12:20 AM To: tewhatuora/api-standards @.> Cc: Pat Ryan @.>; Mention @.> Subject: Re: [tewhatuora/api-standards] Standard PATH Structure for backend servers (Issue #148)
The URI page does provide a template for URI construction but as a change, suggest the following. I'd like feedback on cardinality choices and whether we see this as a MUST or SHOULD
The table below represents the URI hierarchy APIs MUST use: Level Name Cardinality 1 protocol|standard 0..1 2 protocol version Must be provided if protocol|standard is provided and relevant 3 namespace 0..1 4 version 0..1 5 resource 1..1 6 resource-id 0..1 7 sub-resource 0..1 8 sub-resource-id 0..1
Examples: [basePath]/fhir/r4b/nhi/v1/Patient/ZZZ008 [basePath]/fhir/r4b/air/v1/Immunization/_search [basePath]/fhir/r4b/nzps/v1/Patient/$summary [basePath]/contracts/v2/laboratories/33245/locations/P100782 [basePath]/v3/vaccinators/43265/certifications/7281 [basePath]/openid-connect/token
- Reply to this email directly, view it on GitHubhttps://github.com/tewhatuora/api-standards/issues/148#issuecomment-2090360288, or unsubscribehttps://github.com/notifications/unsubscribe-auth/AVNGZRA4HRIQVAPDWUWEWRLZAIVNTAVCNFSM6AAAAABGZUND52VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDAOJQGM3DAMRYHA. You are receiving this because you were mentioned.Message ID: @.***>
Statement of confidentiality: This email message and any accompanying attachments may contain information that is IN-CONFIDENCE and subject to legal privilege. If you are not the intended recipient, do not read, use, disseminate, distribute or copy this message or attachments. If you have received this message in error, please notify the sender immediately and delete this message
ChrisSquats
commented
6 months ago @pat-ryan-health I think this addresses your concerns. Below I've dropped protocol to SHOULD. Also, the guidance for version number is covered under https://apistandards.digital.health.nz/draft/api-development/Synchronous%20APIs/Version%20Control#uri-path-versioning-supported
| Level | Name | Cardinality |
|---|---|---|
| 1 | protocol\|standard |
0..1 MUST if the implementation is a FHIR API |
| 2 | protocol version |
0..1 SHOULD be provided if protocol|standard is provided and relevant |
| 3 | namespace |
0..1 SHOULD be provided |
| 4 | version |
0..1 MAY be provided |
| 5 | resource |
1..1 MUST be provided |
| 6 | resource-id |
0..1 MUST be provided when interacting with a Resource Instance |
| 7 | sub-resource |
0..1 MUST be provided when interacting with a Sub-resource |
| 8 | sub-resource-id |
0..1 MUST be provided when interacting with a Sub-resource instance |
Summary
It would be helpful to have a standard way to construct the backend server api path. This has to be configured on the API GW so it knows where to send the message. Currently https://apistandards.digital.health.nz/api-development/URIs/ has guidance but does not actually state what the standard template should be.
Currently HIP uses this template
/{version}/{namespace}/{version}{resource}/{resource-id}example https://api.hip.digital.health.nz/fhir/nhi/v1/Patient/NHI1234which is compliant with the MoH standard in effect at the time the API was created
Drawbacks
no drawbacks identified.
Which area of the standards does this apply to?