Example URL scheme with POST for Health #217

cookeac · 2021-05-20T05:38:09Z

This is a first experiment with a separate URL scheme for the tag ADE-1.x-health.
It covers health diagnosis, treatment, and treatment programme.
Methods supported are

GET (collection)
POST (to collection - single event)
POST (batches)

This implements SOME of the thinking in #154 but is not yet a fix. More work to be done on Error handling, for example.

URL scheme for ADE-1.x-health with POST and batch POST methods.

Develop

cookeac · 2021-05-20T05:39:06Z

Created this for discussion/comment at the meeting. It can be removed after if on the wrong track.

ahokkonen

Left some review comments.

Our main concern is that this approach would fit perfectly atomic operations, but in our solution, we need to support non-atomic scenarios where party failure/success is allowed. For that we need a mechanism to determinate statuses of the sent resources back from the service response.
So, it is not enough to just have a same resource back in response, but also a status and possible error array for failed resources.

url-schemes/healthURLScheme.json

cookeac · 2021-06-14T10:49:20Z

We discussed both of those previously at our meeting. This does sound like a fairly specific case that is not well supported by widely used standards such as problem details that are indeed atomic. I'd be interested in the HTTP status coffee that you would propose to return when accepting some data but rejecting others. What would this look like to be REST compliant? Andrew Cooke, Managing Director, Rezare Systems m: +64-27-5570822<tel:+64275570822> p: +64-7-8570822<tel:+6478570822>

________________________________ From: Anton Hokkonen ***@***.***> Sent: Monday, June 14, 2021 7:30:52 PM To: adewg/ICAR ***@***.***> Cc: Andrew Cooke ***@***.***>; Author ***@***.***> Subject: Re: [adewg/ICAR] Example URL scheme with POST for Health (#217) @ahokkonen commented on this pull request. Left some review comments. Our main concern is that this approach would fit perfectly atomic operations, but in our solution, we need to support non-atomic scenarios where party failure/success is allowed. For that we need a mechanism to determinate statuses of the sent resources back from the service response. So, it is not enough to just have a same resource back in response, but also a status and possible error array for failed resources.

________________________________ In url-schemes/healthURLScheme.json<#217 (comment)>:

+ ],

+ "parameters": [ + { + "$ref": "#/components/parameters/location-scheme" + }, + { + "$ref": "#/components/parameters/location-id" + } + ], + "requestBody": { + "required": true, + "description": "The collection of health treatment events to create. \nA client MAY fill in resource *Id*s with a client-generated UUID and the server MAY use these *Id*s.\nIf the server does not use the client-specified *Id* field it shall issue its own *Id*s for the resources.\nA client SHALL ensure that the *meta.source* and *meta.sourceId* fields are filled by the client.\nAlthough a collection is used, servers SHALL IGNORE any pagination-related attributes.\n", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/icarTreatmentEventCollection" Do we want to use collection type for posting resources as a batch? Could it by just an array of resources (aka array of icarTreatmentEventResourcce)?

________________________________ In url-schemes/healthURLScheme.json<#217 (comment)>:

+ "description": "The collection of health treatment events to create. \nA client MAY fill in resource *Id*s with a client-generated UUID and the server MAY use these *Id*s.\nIf the server does not use the client-specified *Id* field it shall issue its own *Id*s for the resources.\nA client SHALL ensure that the *meta.source* and *meta.sourceId* fields are filled by the client.\nAlthough a collection is used, servers SHALL IGNORE any pagination-related attributes.\n",

+ "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/icarTreatmentEventCollection" + } + } + } + }, + "responses": { + "200": { + "description": "Successful. The response contains a copy of the collection, as modifed by the server.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/icarDiagnosisEventCollection" This approach only supports "all or nothing" posting - if all ok collection of created resources are posted back if not - list of errors receved. What if we need to support partial success? We need to get statuses on each resource - success or failure with relevant errors. — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub<#217 (review)>, or unsubscribe<https://github.com/notifications/unsubscribe-auth/AKZG77P5ICTAY6G4OJUXPKTTSWV2ZANCNFSM45GDBDPA>.

ahokkonen · 2021-06-15T11:14:43Z

@cookeac
that is true - our case and requirements are a bit out of specs. For https statuses and response we where thinking about the following approach:

Batch operation must return a success status code (200) only if processing of all resources is succeeded.
If any single resource handling fails the whole batch operation must return the failure status code (4xx)
Service response must contain processing information about every resource from batch request including successed and failed. For successed we need to get back server updated information (server generated identifier, for example) and for failed we need to get an information about the failure.

Example for the batch response for one successed and one failed resource handling response

[
    {
        "id": null,
        "meta": {
            "source": "XXXX",
        },
        "errors": [
            {
                "id": null,
                "status": 400,
                "code": null,
                "title": null,
                "detail": "Required field cannot be null: Meta.SourceId",
                "meta": null
            }
        ]
    },
    {
        "id": "5",
        "meta": {
            "source": "XXXX",
            "sourceId": "352178635217635126783",
            "modified": "2021-06-15T11:12:10.7779154Z",
            "creator": "iDDEN.Stub"
        },
        "errors": null
    }
]

ghost · 2021-06-17T08:02:47Z

As discussed in our meeting, it would be nice if we could add "warnings" (similar to errors) so that the receiving system can add those to entities that were accepted, but still something important needs to be reported back. In general, this could also be interesting for a single post as well.

cookeac · 2021-07-01T05:51:28Z

We should revisit batches. Maybe a REST compliant single item POST and a /batches/ post that does not attempt to be compliant with REST norms but instead returns a special purpose result that deals with the identifiers, errors and warnings as discussed. A sort of morph of problem details and success. It should support multi-value error returns.

cookeac · 2021-07-01T07:58:20Z

Changed /batches/ POST to return an array of icarBatchResult instead (in case of both 200 and error). This will contain:

id - issued id
meta - incl source/sourceId
errors (array of icarErrorResource)
warnings (array of icarErrorResource that represents warning messages)

ahokkonen

added some comments/questions

resources/icarBatchResult.json

ahokkonen · 2021-07-19T12:38:47Z

resources/icarBatchResult.json

+            "$ref": "../types/icarMetaDataType.json",
+            "description": "Metadata for the posted resource. Allows specification of the source, source Id to synchronise data."
+        },        
+        "errors": {


could errors and warnings be combines under one field ("norifications") and icarErrorResource (maybe then resource name should be different) have an additional field "severity" to identify the severity level of the message? with that approach we could pass errors, warning and infos withint the same set of resources?

I wondered that too - I separated them because then the client can quickly check to see if an array is empty or not rather than having to look at each item for severity, but I'm open to doing it the other way as well.

I do not have any strong feelings about it :) both solutions would be fine in my opinion.
If we'll decide to go with the combined list then we'll need to define enumeration for severity levels - Info, Warning, Error (maybe Critical?) - where "Error" is an indication for event failure and other are just an additional notification for successed processing.

Renamed icarErrorResource to icarBatchResultMessage, and added icarBatchResultSeverityType enum. Removed errors[] and warnings[] arrays and replaced with messages[].

It seems the rename was not fully done yet? When I run java -jar ~/local/openapi-generator-cli-5.2.0.jar generate -g jaxrs-resteasy -i https://raw.githubusercontent.com/cookeac/ICAR/master/url-schemes/healthURLScheme.json I get a lot of messages stating:
Caused by: java.io.FileNotFoundException: https://raw.githubusercontent.com/cookeac/ICAR/master/resources/icarErrorResource.json

(exampleUrlScheme.json generates fine)

Renamed icarErrorResource to icarBatchResultMessage, and added icarBatchResultSeverityType enum.

Batch POSTS now always return an array of icarBatchResult, each of which may contain an array of icarErrorWarningMessageResource. Single POSTs if successful return the posted object (ID filled in), otherwise they return an errors array of icarErrorWarningMessageResource. Sorry for renaming the file, but it helped to clarify its purpose.

cookeac and others added 3 commits May 20, 2021 17:28

Create healthURLScheme.json

7bd093f

URL scheme for ADE-1.x-health with POST and batch POST methods.

Merge pull request #19 from adewg/Develop

202fd80

Develop

Merge branch 'master' of https://github.com/cookeac/ICAR

596645e

cookeac requested review from ahokkonen and erwinspeybroeck May 20, 2021 05:38

ahokkonen reviewed Jun 14, 2021

View reviewed changes

url-schemes/healthURLScheme.json Outdated Show resolved Hide resolved

url-schemes/healthURLScheme.json Outdated Show resolved Hide resolved

alamers linked an issue Jun 17, 2021 that may be closed by this pull request

Semantics for POST method #154

Closed

Update resource for RFC7801 compliance and Ids

325e9b6

cookeac marked this pull request as draft July 1, 2021 06:07

Added ErrorResource, BatchResult, removed collections

a040753

cookeac marked this pull request as ready for review July 1, 2021 07:58

cookeac requested a review from ahokkonen July 15, 2021 05:50

ahokkonen reviewed Jul 19, 2021

View reviewed changes

cookeac added 3 commits July 26, 2021 20:28

Changes to error and warning handling

38e2ac4

Renamed icarErrorResource to icarBatchResultMessage, and added icarBatchResultSeverityType enum.

Touch files to resolve conflicts

b76071c

cookeac closed this Jul 30, 2021

cookeac reopened this Jul 30, 2021

cookeac closed this Jul 30, 2021

cookeac deleted the master branch August 27, 2021 06:11

ahokkonen mentioned this pull request Dec 7, 2021

Add id to icarResource.json #264

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Example URL scheme with POST for Health #217

Example URL scheme with POST for Health #217

cookeac commented May 20, 2021

cookeac commented May 20, 2021

ahokkonen left a comment

cookeac commented Jun 14, 2021 via email

ahokkonen commented Jun 15, 2021 •

edited

Loading

ghost commented Jun 17, 2021

cookeac commented Jul 1, 2021

cookeac commented Jul 1, 2021

ahokkonen left a comment

ahokkonen Jul 19, 2021

cookeac Jul 19, 2021

ahokkonen Jul 20, 2021 •

edited

Loading

cookeac Jul 26, 2021

alamers Jul 29, 2021

alamers Jul 29, 2021

Example URL scheme with POST for Health #217

Example URL scheme with POST for Health #217

Conversation

cookeac commented May 20, 2021

cookeac commented May 20, 2021

ahokkonen left a comment

Choose a reason for hiding this comment

cookeac commented Jun 14, 2021 via email

ahokkonen commented Jun 15, 2021 • edited Loading

ghost commented Jun 17, 2021

cookeac commented Jul 1, 2021

cookeac commented Jul 1, 2021

ahokkonen left a comment

Choose a reason for hiding this comment

ahokkonen Jul 19, 2021

Choose a reason for hiding this comment

cookeac Jul 19, 2021

Choose a reason for hiding this comment

ahokkonen Jul 20, 2021 • edited Loading

Choose a reason for hiding this comment

cookeac Jul 26, 2021

Choose a reason for hiding this comment

alamers Jul 29, 2021

Choose a reason for hiding this comment

alamers Jul 29, 2021

Choose a reason for hiding this comment

ahokkonen commented Jun 15, 2021 •

edited

Loading

ahokkonen Jul 20, 2021 •

edited

Loading