...
NCMP CMhandle registration endpoint receives multiple operations to create, update or delete cm-handles in a single request. As there are multiple operations, the endpoint response structure should be able to provide the status of all operations separately with consistent error-code to allow users to retrigger failed operations programmatically if possible.
Questions:
# | Question | Agreed Solution | Remarks |
---|---|---|---|
1 | Are multiple operations for one cm-handle is considered invalid input? | No special validation, process as usual |
|
2 | Should system check which dmi-plugin 'owns' cm handle before deleting it? ie. is is the same service that registered the cm-handle | Just delete for now until Acces Control gets implemented | Agreed with stakeholder in meeting |
3 | Preferred output format | Alternative B: only failed cm handles, no status code for each handle. Stakeholder expected that errors are rare and does not want to process data if successful ie. in most cases and empty response is expected (statuscode 200 code) | empty arrays will not appear in json at all. I.e. if there are no 'failed delete cm handles' the 'failedDeletedCmHandles' property will simply not appear in the response. |
4 | Order of processing | Change to: delete → create → update | It will help us to handle the case where the user wants to recreate the cm handle |
Response Structure
HttpStatus
Scenario | Status Code | ResponseBody |
---|---|---|
All operations were successful |
200 | Empty | |
All or few operations failed | 500 | With error details from each failed operation |
Invalid Input | 400 | Error Details |
Response Body
The response body should give enough information in case of errors for user to retry programatically
The response can be sent as a collection or grouped by operation type or cm-handles. If we group the response by operation type it will be simpler for the end-point user to form a new request and sent it again if the error can be resolved with a retry or a few changes.
Code Block | ||
---|---|---|
| ||
{
"cmHandle": "cmHandle-1"
"operation": "CREATE" // This field can be used for grouping response if required
"status": "FAILURE" // Can use the same structure to show success later on.
"error-code": "01" // Only sent in the case of error
"error-text" : "cmhandle already exist" // Only sent in the case of error
} |
for each failed operation to retry them programmatically. For each failed operation we should send the below information
Name | Description | Mandatory? |
---|---|---|
cmHandle | identifies the failed cm-handle |
|
errorCode | Identify the error |
|
errorText | Human-readable error text |
|
status | Failure/Success; To be discussed with the team |
|
The response body can be structured in two ways
Alternative A: Group by operation type, with status fields
The interface is generic and if we need to send the status of all operations in the future it can be achieved without any breaking change.
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
Code Block | ||||||
| ||||||
{ "createdCmHandles": [ { "cmHandle": "cmHandle-1", "status": "FAILURE", // CanExtra use the same structure field to showindicate success later on.the status "error-code": "01" // Only sent in the case of error, "error-text" : "cmhandle already exist" // Only sent in the case of error } ], "updatedCmHandles": [ { "cmHandle": "cmHandle-2", "status": "FAILURE" // Can use the same structure to show success later on., "error-code": "02" // Only sent in the case of error, "error-text" : "cmhandle does not exist" // Only sent in the case of error } ], "deletedCmHandles": [ { "cmHandle": "cmHandle-3", "status": "FAILURE" // Can use the same structure to show success later on., "error-code": "02" // Only sent in the case of error, "error-text" : "cmhandle does not exist" // Only sent in the case of error } ] } |
Alternative B: Group by operation type but only for failed operations
This approach meets the current requirement and has a smaller payload size (no extra field for the status).
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
{ "operationResponsefailedCreatedCmHandles": [ { "cmHandle": "cmHandle-1", "operation": "CREATE", "status": "FAILURE" // Can use the same structure to show success later on. "error-code": "01" // Only sent in the case of error, "error-text" : "cmhandle already exist" // Only sent in the case of error } ], "failedUpdatedCmHandles": [ { "cmHandle": "cmHandle-2" "operation": "UPDATE", "status": "FAILURE" // Can use the same structure to show success later on. "error-code": "02" // Only sent in the case of error, "error-text" : "cmhandle does not exist" // Only sent in the case of error }, {], "cmHandlefailedDeletedCmHandles": [ "cmHandle-3" { "operation": "DELETE", "statuscmHandle": "FAILURE" // Can use the same structure to show success later on.cmHandle-3", "error-code": "02" // Only sent in the case of error, "error-text" : "cmhandle does not exist" // Only sent in the case of error } ] } |
Error handling
The error can be due to client input and they should try not to Expected Error per operations
Input Issues
- If the DMIService ( dmiModelPlugin or dmiService ) does not match with the DMIService of cm handle? update & delete scenario. We should not update these two field because it impacts modelSync, but dmiDataService can be updated
- Multiple operations for a single cm-handle:
- If not allowed: Throw the error; it enables us to process them parallelly for better performance.
- If allowed:
- Which operation type has higher precedence
- create → update → delete:
- delete → create → update: It will help us to handle the case where the user wants to recreate the cm handle
- Multiple within the same operation type
- create → Take the last one and show success or take the first one and let others fail
- update → Process them sequentially because the update can be partial and order may matter here
- delete → Process only once
- Which operation type has higher precedence
- Input is not in the correct expected format: For example, if the user has not defined the "cm-handle"Reject the request
Create CMHandles
- cm-handle already exist
- multiple create operations for one cm-handle
- unknown-error
Update CMHandles
- cm-handle does not exist
- DMIService name does not match with existing DMIService of cm handle
- unknown-error
Remove CMHandles
- cm-handle does not exist: No error
- DMIService name does not match with existing DMIService of cm handle
- unknown-error
Should we indicate if something can be fixed with retry?
Code | Slogan | Applicable to | ||
---|---|---|---|---|
Create | Update | Remove | ||
00 | unknown/other | Yes | Yes | Yes |
01 | cm-handle does not exist | No | Yes | No* |
02 | cm-handle already exist | Yes | No | No |
03 | not allowed** | ? | Yes | Yes |
Notes
* remove will ignore non-existing cm handles (not an error, assume already deleted)
** suggested future error (for illustration purposes)
...