Hi community,
In a project I am supporting, we are currently implementing a set of TMF open APIs for wholesales connectivity. We are struggling with a general issue where we are not sure what the intended usage pattern of the TMF open APIs is. It is about validation and the use of HTTP errors vs. rejected state/status and the implication that state/status is mandatory for a 201 response.
Before formulating our issue more precisely and asking my question, let me state a few facts as defined in the TMF open APIs:
* state/status is mandatory for a 201 response to a POST request (at least defined as such for the majority of APIs with a few exceptions like Account, Agreement, Trouble Ticket, ...)
* acknowledged & rejected: for those APIs using these states, some define both acknowledged & rejected as possible initial states without transition from acknowledged to rejected (Product Ordering, Trouble Ticket, ...) where some others define only acknowledged as initial state with a transition from acknowledged to rejected (Service Order, Resource Order, ...).
* TMF Open APIs support HTTP error codes (4xx, 5xx) -> when a request is rejected at this level, no resource is created, thus there is no state / status defined, there is only the HTTP error response with code & error message
Assuming that:
* all errors at message level validation (schema, conformance profile, ...) are handled as HTTP error responses
* state/status is mandatory for a 201 response to a POST request
* acknowledged & rejected are both defined as initial states without transition from acknowledged to rejected (like in Product Ordering)
-> the rejected state / status will never be reached...
There are different possible approaches to address the situation:
A) acknowledged is defined as the mandatory initial state after message level validation and a transition from acknowledged to rejected must be supported for any further validation error (catalog rules, business rules, ...) -> like in Service Order / Resource Order
B) or the resource has NO state / status value at creation / after message validation -> allowed according to Trouble Ticket swagger & conformance profile
C) a new state / status must be defined prior to acknowledged for message level validation prior to business validation
Our opinion is that approach A) is the best / the intended one. Going for A), we would also consider adding an (optional) state / status "approved" between "acknowledged" and "inProgress" defining that the request is fully validated but not yet in progress.
Or maybe we missed / misunderstood something in the various APIs & design guidelines?
If our understanding of the problem is correct, it would be good that all APIs using acknowledged & rejected are aligned to a common usage pattern and that this pattern is captured to avoid future misunderstandings.
Thanks in advance for your answers!
Best regards, Iwan
------------------------------
Iwan Gramatikoff
Edelweiss Service Consulting
------------------------------