spud023
commented
2 months ago Hi Editors,
Sorry for my lack of screen-availability.... but these issues have been churning in my brain while off-screen, and I can distil what I think a reader would want to know from an introduction into a small expansion of the current text. Feel free to just reflect on what I've added/re-arranged, and adopt or adapt as you see fit if you agree.
This text:
Utilising event-driven, Asynchronous API architectures can significantly enhance interoperability by providing sector API Consumers with:
- Realtime communication - when an update or event occurs in one domain, the relevant information can be shared with interested API consumers in realtime
Could be augmented to say:
Utilising event-driven, Asynchronous API architectures can significantly enhance interoperability by providing sector API Consumers with a subset of the following characteristics:
- Realtime communication - this is a discipline that typically integrates bespoke hardware, software and networking types to control devices safely, using Asynchronous APIs with very small guaranteed maximum delivery times. It is not considered further in this standard, and is described here
- Near Realtime communication - when an update or event occurs in one domain, the relevant information can be shared with interested API consumers in near realtime (as fast as possible given the choice of underlying networks and protcols)
- etc
Then in the "What is an Asynchronous API" section, I would prefigure the use of different network protocols or middleware, and the use of Patterns. This is a candidate edit:
Asynchronous APIs are a type of API which allow for non-blocking communication within systems, without the limitations of a typical synchronous request-reply API. Synchronous APIs typically return or generate data when it is requested by a client, however the use of Asynchronous APIs allows generated data to be transmitted and received, potentially by several other software components supporting Async APIs, immediately after the data changes, or an event has taken place.
These APIs are usually used in Patterns describing interactions by several software components supporting different Asynchronous APIs suited to their role in the Pattern (and potentially augmented by some Synchronous APIs). This means that the interactions in an Asynchronous API moves from the single client and single server relationship pattern in synchronous APIs where the client initiates the request, and waits for a response, to one in which APIs are supported by multiple software components, and traditional "servers" holding and processing data can publishing events to Asynchronous APIs supported by one or many Consumers to implement the Publish/Subscribe Pattern.
In addition, although the non-blocking nature of Asychronous APIs can be supported over HTTP/TCP/IP like REST, this is less efficient than the use of a range of network protocols, middleware, and interaction styles that are referred to "asynchronous", "message-based", "event driven" and so forth. These are non-blocking, and offer a range of guarantees about delivery and the order of delivery, and this specification discusses their suitability for various application types.
Asynchronous APIs have many uses, such as realtime (in human terms) chat applications, software developed using the CQRS Pattern and remote procedure invocation and messaging/data sharing. The primary focus of these standards focus on the messaging and data sharing use cases for Async APIs.
One final thing that I note about the structure of this specification as a whole is that Asynchronous APIs is now placed before Synchronous APIs... perhaps to allow that section to be adjacent to FHIR, but this section seems to assume that Synchronous APIs are already understood, and I'd prefer to see Asynch after Synch. Just my view...
Thanks for your patience with my inefficient proofreading process - hopefully we'll achieve eventual consistency! Keith
Summary
The last para of the intro is also inadequate:
I think the emphasis is the wrong way around: the applications have uses for Asynchronous APIs, and not the other way around. What is "remote procedure invocation", this is what all distributed APIs do (incl REST), directly or indirectly.
As Fowler says in the linked article: "For some situations, this separation can be valuable, but beware that for most systems CQRS adds risky complexity.". I'm glad you're referencing Patterns, but this should start with Listener and maybe other more fundamental patterns that describe Pub/Sub, as previously commented, and maybe other Patterns (as implied buy the "chat" example). The patterns should be noted as clearly in the Application layer, and keep middleware and network protocols (which use the same terminology) in a separate layer. Each multiple addressee message send/receipt involves multiple single transmissions under the covers, and you should surface the patterns that describe the possible permutations. "Asynchronous" is an ill advised headline term for these, as previously noted - as all it implies is non-blocking APIs (with actions, like resending to multiple recipients, or possible call-back replies taken after the API invocation is completed).
If you are not mandating REST (which I thought you were) the transmission protocol layer need a serious discussion of benefits and risks in a parallel section.
The second sentence needs an edit to remove 2 uses of "focus". How about:
Link to standards item
https://apistandards.digital.health.nz/draft/api-development/Asynchronous%20APIs/Introduction#what-is-an-asynchronous-api
Which area of the standards does this apply to?