Content Comparison

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:

Response Structure

HttpStatus

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. 

{
    "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 

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.

Response Structure incl status

{
    "createdCmHandles": [ 
		{
 			"cmHandle": "cmHandle-1",
    		"status": "FAILURE", // Can use the same structure Extra 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).

Response (only failed)

{
    "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
		},		}
	],
 	"failedDeletedCmHandles": [ 
		{
 			"cmHandle": "cmHandle-3"
		 	"operation": "DELETE", 
    		"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
		}
	]
}

Expected Error per operations

...

Error handling

The error can be due to client input and they should try not to 

Input Issues

1. 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

2. Multiple operations for a single cm-handle: 

   1. If not allowed: Throw the error; it enables us to process them parallelly for better performance.

   2. If allowed: 

      1. Which operation type has higher precedence

         1. create → update → delete: 

         2. delete → create → update: It will help us to handle the case where the user wants to recreate the cm handle

      2. Multiple within the same operation type

         1. create → Take the last one and show success or take the first one and let others fail

         2. update → Process them sequentially because the update can be partial and order may matter here

         3. delete → Process only once 

3. Input is not in the

...

1. expected format:

...

1. Reject the request

Create CMHandles

1. cm-handle already exist

2. multiple create operations for one cm-handle

3. unknown-error

Update CMHandles

1. cm-handle does not exist

2. DMIService name does not match with existing DMIService of cm handle

3. unknown-error

...

Remove CMHandles

1. cm-handle does not exist: No error 

2. DMIService name does not match with existing DMIService of cm handle

3. unknown-error

Should we indicate if something can be fixed with retry?

Notes
^* remove will ignore non-existing cm handles (not an error, assume already deleted)
** suggested future error (for illustration purposes)