Open APIs

We would like to get your inputs on a requirement to send additional information as part of the error response.

We have a synchronous API which internally performs the below API callouts in the order mentioned below.

1. Get Quote details

2. Perform Credit Check

3. Update Credit Check Result into quote
4. Update Payment Method Status
5. Take Payment
6. Submit Quote to Product Order

Now, the ask is if any of the steps from 3 to 6 failed, we need to send "what is the reason of failure + what is the credit check result from step 2"

• Below is the existing sample error response defined for step 3 failure.

{

  "code": "EditQuoteError",

  "reason": "Error in editing quote",

  "message": "Error in editing quote",

  "status": "500"

}

• In the above error response, if we have to indicate credit check result from step 2, how can we do it?
• Are we allowed to extend the error response to add an optional attribute like creditCheckResult as below?
• Does it violate TMF OpenAPI error structure?
• Or any other standard guideline we have as per TMF OpenAPI ?

{

  "code": "EditQuoteError",

  "reason": "Error in editing quote",

  "message": "Error in editing quote",

  "status": "500",

   "creditCheckResult': "RED"

}

Hi Pritam, 

In principle TMF 630 Part 1 talks about error response structure extension and Part 23 further elaborates on how to extend properly using schema-based extension. 

However from my point of view, extension is reasonable when it carries additional information about error itself. In the given scenario however, attempt is to convey technically successful result of the preceding operation together with error details of the failure happened in subsequent operation. 

Instead, if consumer is interested in results of the Credit Check, Credit Check API should be called explicitly outside of this multi-step Submit Order API. 

It would be interesting to see other TM Forum community opinions on that topic. 

------------------------------
Denis Kozlov
Telefonica Germany GmbH & Co. OHG
------------------------------

Hi Denis,

Thanks for your response and input  

• As per current solutions we can't remove creditCheck steps from submit order API . There have some asynchronous steps and handling are involved (event driven) for long lived credit check scenarios.
• If we separately call credit check API first for "same customer identifiers + bank account" credit check will be invoked twice for 'Credit Check API call" and part of  'Submit-Order' process API call it's not desirable as well.  CreditCheck  API will not able handle long-lived event driven complexities for IN-Progress credit result scenarios. 

Consumer (Retail/Partner) application business want to display separate set of message and want to navigation to different UX screen based on the following combination technical errors . Result could be "GREEN" , "RED" , "IN-Progress" combination of both.

• GREEN + Technical Error Next Step  -> Response1 Activity UI screen
• RED + Technical Error -> Response2 UI Activity Screen
• Technical Error Before RTCC --> Response3 Activity Screen

Unless API will respond with respective information within in the error response structure,  it would not possible from consumer to handle individual scenario.

Does it violate TMF guideline if we will include following optional attribute in error response ?

Http Status: 500

{

  "code": "EditQuoteError",

  "reason": "Error in editing quote",

  "message": "Error in editing quote",

  "status": "500",

  "details": [{"name": "CreditCheck", "value": "RED"}]

}

------------------------------
Pritam Roy
Tech Mahindra Limited
------------------------------

Hi Pritam,

As Denis said, the TMF 630 Part 1 states that "@type and @schemaLocation SHOULD be used for run time extension of the error." And a small correction, not Part 3, but Part 2 contains "Extension patterns" and describes Schema based extension.

As I understand, Perform Credit Check is a Task request that successfully completed, and its result is used to check subsequent API calls. In this case, it may be reasonable to indicate the result of the previous call in the error.

Hi Yurli,

Thanks for your valuable input. Your assumption is correct . I have detailed out problem statement in above reply.

Consumer of the "Submit Order" coarse grained API want to navigation to different UX screen based on the following combination technical errors scenario . Result could be "GREEN" , "RED" , "IN-Progress" combination of both.

• GREEN + Technical Error Next Step  -> Response1 Activity UI screen
• RED + Technical Error -> Response2 UI Activity Screen
• Technical Error Before RTCC --> Response3 Activity Screen

------------------------------
Pritam Roy
Tech Mahindra Limited
------------------------------

Hi Pritam,

If you don't want to violate TMF guidelines, your error extension should look like this:

{
    "code": "EditQuoteError",
    "reason": "Error in editing quote",
    "message": "Error in editing quote",
    "status": "500",
    "details": [
        {
            "name": "CreditCheck",
            "value": "RED"
        }
    ],
    "@type": "EditQuoteError",
    "@baseType": "Error",
    "@schemaLocation": "/performCreditCheck/schema/EditQuoteError.yml"
}

Hi Yurii,

Thank you so much for your kind support. We are following similar structure.

{    "code": "EditQuoteError",    "reason": "Error in editing quote",    "message": "Error in editing quote",    "status": "500",    "details": [        {            "name": "CreditCheck",            "value": "RED"        }    ],    "@type": "EditQuoteError",    "@baseType": "Error",    "@schemaLocation": "/performCreditCheck/schema/EditQuoteError.yml"}

Hello,

I understand your use case is about credit check and how to "merge" the various "errors" from dependent services.

First, I'd to recommend to avoid using the term "error". because it's not an error. It's a validation result.

I don't recommend following TMF630 as a guide for mananing errors as these are not errors.

error should only refer to HTTP status codes.

for credit check, we don't have error but validation result, wich could be a rating, a scope, a status etc.

what you need is a sub-resource in your API contract that represent a list of validation type/reaons/code/... representing the rating of the customer.

if you need suggestion on how to represent credit check validation, you can take inspiration from existing API that contain validation result:

• TMF679 (product offering qualification) has validation result about product offer eligibility
• TMF645 (service qualifiation) has validation about technical feasability
• TMF760 (Product Configuration) has dedicated sub resource for credit check

we use these API and have made some small extension to provide additional details. the model is quite flexible.

As for your question about aggregating validations. we have adopted this approach:

we created a composite qualification API that bundles TMF679 (only the qualification part) and TMF645.

the composite has both payloads and also has an aggregator of all validations. Composition solves 2 issues

• API clients have a single endpoint
• we solve TMF APIs inconsistencies in the semantic
  • 645 has a sub-resource called EligibilityResultReason while 679 use another name: EligibilityUnavailabilityReason
  • but both resource have the same attributes: code and reason to which we added status and period

You can add sub-resource and attributes (we added 2 attributes: status and period).

Lastly if you want to keep your TMF API conformant, you can check the "conformance profile (RAND)" pdf document provided in the TMF API table.

Hope this helps,

------------------------------
Kind regards,

Matthieu Hattab
Lyse Platform
------------------------------

Hello Matthieu,

Thanks for you detail feedback will definitely look it in detail . Thanks for sharing this approach will try to implement same as and when arise such scenarios.