CHANGE REQUEST] Define Error Codes for upcoming customer module

[zerwuff]

API Version

TOMP 1.5

Summary

As we provide the TO side of the TOMP API alongside with new features like /registration (to enable minimal transport of customer ids and their names to our system).
We would like to assign error codes for that registration process in a new range under https://github.com/TOMP-WG/TOMP-API/wiki/Error-handling-in-TOMP#module-number-table

Expected Behavior

Please extend https://github.com/TOMP-WG/TOMP-API/wiki/Error-handling-in-TOMP#module-number-table with a new Section
"8 Customer Errors" indicating that errors for that range occur during error processing of the customer API within the TOMP modules

Current Behavior

Now, ne would throw "sidecar API errors" (like /customer/registration) that come along with TOMP with their own error style, which makes integration of TOMP and extensions very hard.

Possible Solution

Extend https://github.com/TOMP-WG/TOMP-API/wiki/Error-handling-in-TOMP#module-number-table with a new error module Section "8 - Customer Module " that will allow us to use this range.
Possible Errors would be

{ "errorCode": 8001,
"type": "Customer",
"title": "Registration Failed",
"detail": "Registering of this customer is not possible because of reason A ",
"instance": "889bf030-8963-11ea-b110-63982e64cb91" }
{code}

{ "errorCode": 8xxx,
"type": "Customer",
"title": "Could not change customer",
"detail": "Patching of this customer is not possible because of reason X",
"instance": "889bf030-8963-11ea-b110-63982e64cb91" }
{code}

Steps to Reproduce

This is a design decision

Context (Environment)

We would like to extend the TOMP API 1.5 alongside with additional endpoint: /customer that handles a minimal customer API endpoints (Register and patch customer at first).
For error cases (cannot register customer, we need an error response object and want to reuse the TOMP error response to make the integration of this endpoint easier.
{code}

Detailed Description

Extend https://github.com/TOMP-WG/TOMP-API/wiki/Error-handling-in-TOMP#module-number-table with a new error module Section "8 - External Errors" that will allow us to use this range offically.

Describe usage of this error codes:

{ "errorCode": 8xxx, <-- Range of the code
"type": "Customer",
"title": "Registration Failed", <-- title of the error
"detail": "Registering of this customer is not possible because of reason X", <-- description of the error
"instance": "889bf030-8963-11ea-b110-63982e64cb91" }
{code}

Possible Implementation

[matt-wirtz]

Hi! I think the /registration you are mentioning has huge overlaps with the proposal for explicit customer registration described in this issue: #549
There is already a proposed specification linked to the issue. Maybe you can have a look and provide feedback.

Your issue here regarding a missing error module adds to the explicit customer registration process quite nicely. I think the idea to have a new module 'customer' with number 8 makes sense. You were already providing some general example like "Registering of this customer is not possible because of reason X".

Could you add a list of errors that should be explicitly standardized? I assume there is more then the above mentioned one.

[zerwuff]

hi Mat, this makes sense to me. Shall i merge both tickets or close mine ?
I highly appreciate the customer module & error codes as we see the need as TO for some cases at least to provide minimal customer support.

Right now we have following possible error cases, assuming module error codes 8xxxx

//Registration
80001 - Missing Required Fields for customer registration // A general 400x for registration
80002 - Field does not match required pattern for customer registration // wrong email address
80003 - Customer with that data Id an MaaS Id combination already existing and cannot be registered twice // We verify uniqueness of CustomerId per MaaS Platform Id for registration - alternatively: general constraint violation message
80004 - Customer with given data already existing and cannot be registered twice // Recognized some other violation of uniqueness, e.g. simular name and address detected

// patch customer data
80010 - Could not change customer data // use case: change customer Data like email address
80020 - Could not delete customer // For un-registering customers

[matt-wirtz]

Thx @zerwuff for the list. I will add them to the Wiki page (https://github.com/TOMP-WG/TOMP-API/wiki/Error-handling-in-TOMP) once the explicit customer registration is finalized.
Could you rename your issue? Maybe "Extend Error Codes for explicit customer registration (customer module)"?

[zerwuff]

@matt-wirtz title changed, i think this is more clear