| Message | NEW | XXXX | NNNN |
|---|---|---|---|
| Patient block (see 6 - Administration) | Y | DRB3/4/5 | DRB3/4/5 |
| Donor block (see 6 - Administration) | Y | DRB3/4/5 | DRB3/4/5 |
| Typing response | Y | DRB3/4/5 | DRB3/4/5 |
| Sample response | Y | DRB3/4/5 | DRB3/4/5 |
As previously indicated in Section 2.1, the OpenAPI specification forms an integral component of our updated documentation set. Henceforth, we will refer to this API documentation as "Swagger." You can access it via the following publicly available URL: https://apispecs.wmda.info/
At this address one can find both Search & Match API specifications and Connect API specifications:
Since the communication is now split to communication with WMDA's Search & Match and messaging with other registries, each API request in this semantics document may be represented in two styles:
Wherever suitable, we included EMDIS names of the messages in parentheses, e.g. 5.1 - Extended Typing Request (TYP_REQ).
In contrast to the flat FML messages used in the EMDIS communication, the REST API based Match-Connect communication uses nested (multi-level) data structures. Furthermore, the field designations have been improved, e.g. the EMDIS field REQ_DATE is named as requestDate in the API model classes.
EMDIS rules from the EMDIS Semantics are modified accordingly to the REST API based approach and are added to each message, where applicable.
The table below shows recommended sets of API endpoints to be implemented depending on your use of services:
Service in use API endpoint \ | Comment | Recommended for Patient & Search | Recommended for Patient & Search, download Registry | Mandatory for Connect | Mandatory for Connect, Download Registry | Comment |
|---|---|---|---|---|---|---|
| SEARCH & MATCH | ||||||
| PATIENTS | ||||||
| /patients [POST] | Create a patient | yes | no | yes (PR) | no | |
| /patients [PUT] | Update an existing patient | no | no | yes (PR) | no | |
| /patients [GET] | Retrieved patients list | no | no | no | no | Search and Match Service Graphical User Interface (GUI) content, optional for participating organisations |
| /patients/{wmdaId} [GET] | Retrieve | no | no | no | no | Search and Match Service GUI content, optional for participating organisations |
| /patients/status [PUT] | yes | no | no | no | ||
| /patients/user [PUT] | no | no | no | no | Search and Match Service GUI content, optional for participating organisations | |
| SEARCH | ||||||
| /searches [POST] | yes | no | yes (PR) | no | for recommendations see semantics  | |
| /searches/patientSearches/{wmdaId} [GET] | yes | no | yes (PR) | no | ||
| /searches/refreshAllPatientSearches [POST] | no | no | no | no | Search and Match Service GUI content, optional for participating organisations | |
| /searches/{searchId} [GET] | no | no | no | no | highly recommended | |
| /searches/refreshAllPatientSearches [POST] | no | no | no | no | ||
| /searches/searchResults/donors [POST] | yes | no | yes (PR) | no | at least one of those is mandatory, | |
| /searches/searchResults/cbus [POST] | ||||||
| /searches/{searchId}/searchResults/adcu [GET] | ||||||
| /searches/{searchId}/searchResults/registries [GET] | no | no | no | no | Search and Match Service GUI content, optional for participating organisations | |
| /searches/{searchId}/searchResults/cbbs [GET] | no | no | no | no | Search and Match Service GUI content, optional for participating organisations | |
| /searches/selected/donors [POST] | no | no | no | no | Search and Match Service GUI content, optional for participating organisations | |
| /searches/selected/cbus [POST] | no | no | no | no | Search and Match Service GUI content, optional for participating organisations | |
| /searches/donors/{searchResultsId} [GET] | no | no | no | no | Search and Match Service GUI content, optional for participating organisations | |
| /searches/cbus/{searchResultsId} [GET] | no | no | no | no | Search and Match Service GUI content, optional for participating organisations | |
| DASHBOARD | ||||||
| for all | no | no | no | no | Search and Match Service GUI content, optional for participating organisations | |
| CONNECT API | ||||||
| ATTACHMENT | ||||||
| /api/v1/attachmentTicket [POST] | no | no | Optional for participating organisations | |||
| /api/v1/attachmentDownloadURL [POST] | no | no | Optional for participating organisations | |||
| /api/v1/attachmentDownloadedNotification [POST] | no | no | Optional for participating organisations | |||
| RETRIEVE | ||||||
| /api/v1/availableMessages [POST] | yes | yes | check with Mark | |||
| ADMIN | ||||||
| /api/v1/alertRetrieve [GET] | no | no | recommended | |||
| /api/v1/alertUpdateRetrieve [GET] | no | no | recommended | |||
| PATIENT | ||||||
| /api/v1/updateRegisteredPatient [POST] | yes (PR) | yes (PR) | ||||
| /api/v1/updateRegisteredPatientRetrieve [GET] | yes (DR) | yes (DR) | ||||
| PING | ||||||
| /api/v1/pingRequest [POST] | no | no | Optional for participating organisations | |||
| /api/v1/pingRetrieve [POST] | no | no | Optional for participating organisations | |||
| TEXT MESSAGE | ||||||
| /api/v1/textMessageRequest [POST] | no | no | Optional for participating organisations | |||
| /api/v1/TextMessageRetrieve [GET] | no | no | Optional for participating organisations | |||
| REQUEST | ||||||
| /api/v1/genericRequestRequest [POST] | no | no | ||||
| /api/v1/genericRequestRetrieve [GET] | no | no | ||||
| /api/v1/extendedTypingRequestRequest [POST] | yes (PR) | yes (PR) | ||||
| /api/v1/extendedTypingRequestRetrieve [POST] | no | no | recommended for DCs with incompletely typed donors | |||
| /api/v1/extendedTypingResponseRequest [POST] | no | no | recommended for DCs with incompletely typed donors | |||
| /api/v1/extendedTypingResponseRetrieve [POST] | yes (PR) | yes (PR) | ||||
| /api/v1/sampleRequestRequest [POST] | yes (PR) | yes (PR) | ||||
| /api/v1/sampleRequestRetrieve [POST] | yes (DR, CBB) | yes (DR, CBB) | ||||
| /api/v1/sampleInfoRequest [POST] | yes (DR, CBB) | yes (DR, CBB) | ||||
| /api/v1/sampleInfoRetrieve [POST] | yes (PR) | yes (PR) | ||||
| /api/v1/sampleArrivalRequest [POST] | yes (DR, CBB) | yes (DR, CBB) | ||||
| /api/v1/sampleArrivalRetrieve [POST] | yes (PR) | yes (PR) | ||||
| /api/v1/sampleResponseRequest [POST] | yes (PR) | yes (PR) | ||||
| /api/v1/sampleResponseRetrieve [POST] | yes (DR, CBB) | yes (DR, CBB) | ||||
| /api/v1/infectiousDiseaseMarkerRequest [POST] | yes (PR) | yes (PR) | ||||
| /api/v1/infectiousDiseaseMarkerRequestRetrieve [POST] | yes (DR) | yes (DR) | ||||
| /api/v1/infectiousDiseaseMarkerResultRequest [POST] | yes (DR) | yes (DR) | ||||
| /api/v1/infectiousDiseaseMarkerResultRetrieve [POST] | yes (PR) | yes (PR) | ||||
| /api/v1/reservationRequestRequest [POST] | yes (PR) | yes (PR) | under discussion in user group | |||
| /api/v1/reservationRequestRetrieve [POST] | yes (DR) | yes (DR) | ||||
| /api/v1/reservationResponseRequest [POST] | yes (DR) | yes (DR) | ||||
| /api/v1/reservationResponseRetrieve [POST] | yes (PR) | yes (PR) | ||||
| /api/v1/reservationReleaseRequest [POST] | yes (PR) | yes (PR) | ||||
| /api/v1/reservationReleaseRetrieve [POST] | yes (DR) | yes (DR) | ||||
| /api/v1/requestCancellationRequest [POST] | yes (PR) | yes (PR) | ||||
| /api/v1/requestCancellationRetrieve [POST] | yes (DR) | yes (DR) | ||||
| /api/v1/requestRejectedRequest [POST] | yes (DR) | yes (DR) | ||||
| /api/v1/requestRejectedRetrieve [POST] | yes (PR) | yes (PR) | ||||
| /api/v1/resultReminderRequest [POST] | no | no | recommended | |||
| /api/v1/resultReminderRetrieve [POST] | no | no | recommended | |||
| GENERAL | ||||||
| /api/v1/messageResponse [POST] | yes | yes | ||||
| /api/v1/messageResponseRetrieve [POST] | yes | yes | ||||
| /api/v1/messageAcknowledgementRequest [POST] | all replaced by the messageResponse | |||||
| /api/v1/messageAcknowledgementRetrieve [POST] | ||||||
| /api/v1/warningRequest [POST] | ||||||
| /api/v1/warningRetrieve [POST] | ||||||
| /api/v1/messageDenialRequest [POST] | ||||||
| /api/v1/messageDenialRetrieve [POST] | ||||||
| CBU | ||||||
| /api/v1/cordBloodUnitReportRequestRequest | on hold | no | no | should be generalised to CBU and ADCUs, etc... | ||
| /api/v1/cordBloodUnitReportRequestRetrieve | on hold | yes (CBB) | yes (CBB) | |||
| /api/v1/cordBloodUnitReportResponseRequest | on hold | no | no | |||
| /api/v1/cordBloodUnitReportResponseRetrieve | on hold | yes (CBB) | yes (CBB) | |||
The general reasons behind message ordering are:
Message ordering will be realized by:
For the message ordering to work properly there are different responsibilities of the different parties invovled:
The sender is responsible for ensuring the desired order of calls to the Connect APIs. If API calls are to be scheduled / batched, it is suggested that the sender maintain a queue of outgoing calls / messages so that message sequence is persistent in the event of system failure. Make sure the next message is sent only when the status of the previous one has been marked "OK" by SMC.
Central system provides the same sequence number as below as part of the meta block in the answer in each connect message (messages to another Registry).
Central system provides the same sequence number as above as part of the meta block in the message retrieved by the recieving registry.
The sequence number is part of the meta block. The receiver has to check that the sequence number is correct (no numbers missing) and only process the messages if that is ok. Otherwise go back to the central system and claim the missing message.
Pro:
How to collect all messages and keep the sequence:
The actual messages have to be collected via individual API calls against the different "retrive" APIs. In order to streamline that process a "master"-retrieve API (/api/v2/availableMessages) is provided that returns a list of individual "retrieve" APIs that contain waiting messages for the retrieving registry. The availableMessages API will list per "retrive" API the sequence number(s) of the waiting message(s) in an array. Each "retrive" API will have the optional parameter "sequenceNumber", that allows for an indivual collection of that specific message. If that parameter is left empty all available messages are retrieved.
It is left for the retrieving registry to choose how to collect the messages:
A) collect an overview via the availableMessages and then collect the messages one by one in the order given by the sequence number or
B) collect an overview via the availableMessages and then collect all waiting messages and ensure the correct order of processing of the messages in the local system
C) pull all "retrieve" APIs without checking first the availableMessages APIs and ensure the correct order of processing of the messages in the local system
An additional "All-in-One Queue" is under discussion:
Such a queue would provide all waiting messages in the order of the sequence number directly as return value of the call not only the information which (sequence number) and what (retrive API) kind of messages are waiting for retrieval.
Technicaly this could be realized by:
This would allow a registry to call just one endpoint to collect all messages.
Limitations:
This option doesn't work for all applications/tooling, like defining custom API connectors in the 365 PowerPlatform. In those cases the same static structure for all call responses on a specific endpoint is not only IBP but also required.
As on WMDA side (propably) all messages are stored in one queue/store anyhow (check with Mark) both options will only effect the exposure of the messages to the registries and not the internal workings on WMDA side.
So implementing the options next to each other might give the registries the choice to pick there prefered solution and might still be fine for WMDA?!?