Page History

...

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 formed in three ways

Group by operation type 

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.

{
    "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
		}
	],
 	"deletedCmHandlesfaileddeletedCmHandles": [ 
		{
 			"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
		}
	]
}

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

{
    "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
		},
		{],
 			"cmHandledeletedCmHandles": [ "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

Input Issues

1. Multiple operations for a single cm-handle:. 
2. Input is not in the correct format: For example, if the user has not defined the "cm-handle"

...

1. cm-handle does not exist: No error 
2. unknown-error

Should we indicate  if something can be fixed with retry ?

...