| Jira Legacy | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|
|
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 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
...
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
{
"createdCmHandles": [
{
"cmHandle": "cmHandle-1",
"status": "FAILURE", // Extra field to indicate the status
"error-code": "01",
"error-text" : "cmhandle already exist"
}
],
"updatedCmHandles": [
{
"cmHandle": "cmHandle-2",
"status": "FAILURE" ,
"error-code": "02" ,
"error-text" : "cmhandle does not exist"
}
],
"faileddeletedCmHandlesdeletedCmHandles": [
{
"cmHandle": "cmHandle-3",
"status": "FAILURE" ,
"error-code": "02" ,
"error-text" : "cmhandle does not exist"
}
]
} |
...
This approach meets the current requirement and has a smaller payload size (no extra field for the status).
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
{
"failedCreatedCmHandles": [
{
"cmHandle": "cmHandle-1",
"error-code": "01",
"error-text" : "cmhandle already exist"
}
],
"failedUpdatedCmHandles": [
{
"cmHandle": "cmHandle-2",
"error-code": "02" ,
"error-text" : "cmhandle does not exist"
}
],
"deletedCmHandlesfailedDeletedCmHandles": [
{
"cmHandle": "cmHandle-3",
"error-code": "02" ,
"error-text" : "cmhandle does not exist"
}
]
} |
...
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)
...