| 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 | |
| 3 | Preferred output format | Alterntive B. empty arrays will not appear in json at all | Team prefers alternative A; with 'status' field |
| 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)
...