Clarify optional portions of Service Root URL format

adamjlees commented 7 years ago

https://nhsconnect.github.io/gpconnect/development_fhir_api_guidance.html#service-root-url

Uplift the above page to clarify that providers may configure optional segment(s) of the URL path in order to handle non-GP Connect traffic on the same web server.

For example : https://provider.nhs.uk/GP0001/STU3/2/gpconnect

The extra segment SHALL be static across the provider's GP Connect API endpoints. It SHALL only differentiate between GP Connect and non-GP Connect URLs and SHALL not carry business logic or any other data that is specific to the interaction type, the organisation, the patient or any other concept at a lower granular level than the GP Connect API.

To be decided whether we support 1 or >1 static segments, and whether we support them:

between hostname and ODS
between ODS and FHIR version
between FHIR version and API version
after API version

It may also assist to include a regex expression

adamjlees commented 7 years ago

@briandiggle made the valid point that extra items between the other specified URL segments may cause URL parsing issues in future API management layers.

james-answer commented 7 years ago

The URL on which the provider serves their FHIR endpoint does not matter in the workflow for a consumer. For example:

The provider registers url "https://provider.net" on the SDS against their ODS Code for the "Read a patient" interaction.
The consumer looks up an endpoint for the providers ODS Code and the interaction "Read a patient", they get back from SDS "https://provider.net".
The provider constructs the Fhir request by appending the providers url to the fhir request, "https://provider.net/Patient/27" and sends the request which returns the correct response.

At no point in the process does the consumer care what the URL says or contains, it knows that the url it has is where it needs to send the request as it followed the process on the SDS. To a consumer the url is just a string they need to put before the fhir request so it does not matter if it contains the ODS Code, Fhir Version or any other information.

This API management layer is becoming a magical black box which sit between the consumer and provider and does loads of stuff but the consumer still needs to look up the endpoint where the request needs to be send which makes no sense. If we were going to do some dynamic routing or endpoint lookup centrally it would be better for the consumer to just make a request to the SSP with the target ODS Code, the interaction being sent and interaction version, which could be the "Ssp-InteractionId" header if it contained the interaction version:

Example: If the interaction and interaction version is in the URL: https://SpineSecurityProxy/B00012/urn:nhs:names:services:gpconnect:fhir:rest:read:patient/1/Patient/27

Example: If the interaction and interaction version was in the Ssp-InteractionId header: https://SpineSecurityProxy/B00012/Patient/27

If the routing and endpoint lookup is done by the SSP and is hidden from the consumer it still does not matter what the URL contains as the process of registering an endpoint, looking up the endpoint and building the final URL for the request will be the same as the process for the consumer doing it but the SSP will do the lookup and build the url instead.

briandiggle commented 7 years ago

Agree that at run-time the consumer is agnostic to the contents of the endpoint URL.

The provider may care about URL format as there may be an load balancing or URL rewriting layer at the provider boundary which is operating off the URL.

Also agree with sense of James's comments about the future role of SSP/API Managaement layer to make life easier for the consumer. It is desirable to hide complexity of PDS/SDS interaction from the consumer, and this can be done at the intermediate layer. The intermediate layer (call it API Management or SSP) should expose a simplified interface for consumers to call into.

Whether the SSP is in future exposed directly or sits behind the API management layer is up for grabs. We could have something like this at the API layer, with the interaction stuff in headers: https://gpconnect.api.nhs.uk/B00012/Patient/27

adamjlees commented 7 years ago

Given the discussion above, suggest we clarify the spec so that a suffix at the end of the FHIR base URL

nhsconnect / gpconnect

Clarify optional portions of Service Root URL format #293