Open APIs

Hi,

As I understand the resource model of QueryServiceSpecification, there must be one searchCriteria in POST, and 0..* serviceQualificationItem objects that I interpret as the results of the query in the response. That interpretation is substantiated by the examples.

However, in the API User Guide v4.0.1, the serviceQualificationItem is listed as patchable in the PATCH requests.

I interpret this as implying that for compliance, the API must support the query results as patchable.

Patching the searchCriteria makes sense - the user wants to re-use the same query with altered criteria.

But what is the intended meaning of patching the query results?

Is an API compliant, if it just accepts and ignores the serviceQualificationItem in PATCH, just returns re-evaluates the searchCriteria?

Consider, that a previous serviceQualificationItem element might not even exist anymore when the searchCriteria are re-evaluated in PATCH.

------------------------------
Peter Bruun
Hewlett Packard Enterprise
------------------------------

Hi Peter

I think this is a mistake - I believe that Open API task resources should not be patchable. Clearly for a task that is executed synchronously it makes no sense to patch the task entity (even if the task is persisted). However also for a task that is executed asynchronously it doesn't work to patch the entity - the task is running and it is not clear in the general case how the execution could be affected by a change.

There are exceptions - the obvious one is for an order, where we do allow inflight changes. But orders are considered as first-class managed business entities, not tasks.

I've looked through our design guidelines and I could not see that this was addressed, so I plan to open an issue for that.

Hi,

As I understand the resource model of QueryServiceSpecification, there must be one searchCriteria in POST, and 0..* serviceQualificationItem objects that I interpret as the results of the query in the response. That interpretation is substantiated by the examples.

However, in the API User Guide v4.0.1, the serviceQualificationItem is listed as patchable in the PATCH requests.

I interpret this as implying that for compliance, the API must support the query results as patchable.

Patching the searchCriteria makes sense - the user wants to re-use the same query with altered criteria.

But what is the intended meaning of patching the query results?

Is an API compliant, if it just accepts and ignores the serviceQualificationItem in PATCH, just returns re-evaluates the searchCriteria?

Consider, that a previous serviceQualificationItem element might not even exist anymore when the searchCriteria are re-evaluated in PATCH.

------------------------------
Peter Bruun
Hewlett Packard Enterprise
------------------------------

Thanks a lot.

I could see some meaningful uses, like adding a free-text "Comment" on one of the resulting query items for hand-over of a persisted query to another person. But that would require that the search or query results do not change, because the id of the query item might then not be the same as the id that was used in the PATCH.

So I can see why the standard would allow providing the list of serviceQualificationItem in the request API. There just needs to be a note saying that the implementation is not required to handle the list if provided.

The searchCriteria, on the other hand are identified by the submitter - and there can be only one searchCriterion. So even though the QueryServiceQualification is a task resource, patching the searchCriteria does make sense as an alternative to creating a new QueryServiceQualification every time the criteria are modified.

P.S. I am slightly puzzled why property names for lists are singular, but the name of the single search criterion is plural.

Hi Peter

I think this is a mistake - I believe that Open API task resources should not be patchable. Clearly for a task that is executed synchronously it makes no sense to patch the task entity (even if the task is persisted). However also for a task that is executed asynchronously it doesn't work to patch the entity - the task is running and it is not clear in the general case how the execution could be affected by a change.

There are exceptions - the obvious one is for an order, where we do allow inflight changes. But orders are considered as first-class managed business entities, not tasks.

I've looked through our design guidelines and I could not see that this was addressed, so I plan to open an issue for that.

Hi,

As I understand the resource model of QueryServiceSpecification, there must be one searchCriteria in POST, and 0..* serviceQualificationItem objects that I interpret as the results of the query in the response. That interpretation is substantiated by the examples.

However, in the API User Guide v4.0.1, the serviceQualificationItem is listed as patchable in the PATCH requests.

I interpret this as implying that for compliance, the API must support the query results as patchable.

Patching the searchCriteria makes sense - the user wants to re-use the same query with altered criteria.

But what is the intended meaning of patching the query results?

Is an API compliant, if it just accepts and ignores the serviceQualificationItem in PATCH, just returns re-evaluates the searchCriteria?

Consider, that a previous serviceQualificationItem element might not even exist anymore when the searchCriteria are re-evaluated in PATCH.

------------------------------
Peter Bruun
Hewlett Packard Enterprise
------------------------------