search

tewhatuora / api-standards

Health New Zealand | Te Whatu Ora API Development and Security Standards
https://apistandards.digital.health.nz
Other
9 stars 1 forks source link

[FEEDBACK] - AsyncAPI - Message Concepts #143

Closed mathusmith closed 4 months ago

mathusmith commented 5 months ago

Summary

Add "Event Producer" to the table of concepts. Need to clarify the distinction of "API Provider" and "Event Producer" in the subsequent text. In an Event Broker model the AsyncAPI API Provider is in effect the Event Broker not the originating producer of the event. For example under https://apistandards.digital.health.nz/draft/api-development/Asynchronous%20APIs/MessageTypes#message-body there is the following statement

This message type SHOULD be used if the API Provider does not have full control or knowledge of the event data being sent.

My interpretation is the API Provider is referring to the originating producer of the event but it is not clear.

Link to standards item

https://apistandards.digital.health.nz/draft/api-development/Asynchronous%20APIs/Concepts

Which area of the standards does this apply to?

kyle-mwnz commented 5 months ago

Hi @mathusmith thank you for picking this up.

As part of the current draft version, Message Producer has been added to the list of standard components which are detailed on this page, which is used throughout the section. I agree we should list it alongside the concepts so it can be read in context with the other concepts. Do you have an opinion on Message Producer vs Event Producer?

spud023 commented 5 months ago

Hi all,

I have just retrieved some of these GitHub messages from my over-ambitious SPAM filter... and I think I'll now get them directly, so sorry if this comment is late.

To answer @kyle-mwnz 's question... I think "Message Producer" is good. When contributing to/assisting in editing the CORBA Event Notification Service, "Events" were considered to be "things that happen somewhere", and the word Event was always qualified by "Notification" to represent the technical data artefact that is to be communicated about the event. And then the Event Notifications could have Message Types (just like you have specified in https://apistandards.digital.health.nz/draft/api-development/Asynchronous%20APIs/MessageTypes). But as long as the document is consistent, it doesn't really matter which nomenclature you use.

My main concern is about the terminology "API Producer" and "API Consumer" (in https://apistandards.digital.health.nz/draft/api-concepts/ComponentDefinitions) are very much tied to who writes the specification for "an API" and then supports that specification using a software system (usually a healthcare provider), while API Consumer is the software system that is Patient (Health Consumer)-, Iwi- or Whānau-facing as shown in diagrams that follow the definitions. This Producer/Consumer dichotomy works OK when considering Synchronous APIs, as the Producer of the information is also the API Producer, and supports the software that hosts the API implementation which is invoked ("Consumed") by the API Consumer, which is the software that is being used to query or update information at the API Producer. Simply - it is a Client/Server model, and is reified using REST/FHIR, which are also Client/Server paradigms. However, when you get to "Asynchronous APIs", there needs to be a way of allowing both Producers and Consumers, as defined above to act as both client and server, and also to allow Message Brokers and other Middleware constructs to be intermediate servers and clients. There is no definition given for a granular API (GAPI for convenience), such required by Publish/Subscribe. In the simplest case, where a Consumer wants to subscribe to events that occur in the Producer, firstly the "API Consumer" is the client to a Subscription GAPI, hosted at the "API Publisher", but then once events start happening inside the Producer's software, and messages are transmitted to the "Consumer API", which must support an "Event Consumer" GAPI that takes the server role, and is invoked by the software of the "Producer API", which takes the client role. Then if you insert a Message Broker into the patterns, multiple GAPIs are used by all three participants to achieve a subscription, followed by event message deliveries.

Then in the introduction, a use case for Unified Patient Record is given, and then even the "Producer API" and "Consumer API" distinction breaks down, as we now have (possibly more than 2) peer, or master/copy Producers synchronising with each other back and forth using event notification messages, with or without message brokers involved. In order to describe this properly, a GAPI (or perhaps some more elegant term) is needed as a concept to explain which types of GAPI are supported by which software systems in order for information to flow to the right places.

The definition of "API Designer" given is as close as you come to clarifying that multiple software ystems by run by different roles in the Health System must implement the appropriate parts of the API design... but it's not acknowledged that GAPIs are the units of those API Designs, and implementations must implement these GAPIs to play a certain role (of which there are more than just 2: "API Producer" and "API Consumer"). Each role in the API design -- at least 4 are identified above: information host, peer or subordinate information host, information consumer/updater, and message broker -- are given above, and must implement some subset of the GAPIs, and know what role they are playing in the Application Pattern.

mathusmith commented 4 months ago

Message Producer is fine and is used consistently. The ambiguity I raised has been resolved. Happy with the resolution of this issue.