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"

}

------------------------------
Pritam Roy
Principal Solution Architect
Tech Mahindra Limited
------------------------------

Hi Pritam, 

In principle TMF 630 Part 1 talks about error response structure extension and Part 3 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

Original Message:
Sent: Sep 04, 2024 04:04
From: Pritam Roy
Subject: How To Extend Error Response Payload With Optional Attribute

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"

}

------------------------------
Pritam Roy
Principal Solution Architect
Tech Mahindra Limited
------------------------------

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,

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.

------------------------------
Yurii Yushchak
System Manager
Ericsson Inc.

Original Message:
Sent: Sep 04, 2024 04:04
From: Pritam Roy
Subject: How To Extend Error Response Payload With Optional Attribute

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"

}

------------------------------
Pritam Roy
Principal Solution Architect
Tech Mahindra Limited
------------------------------

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

Original Message:
Sent: Sep 05, 2024 06:22
From: Yurii Yushchak
Subject: How To Extend Error Response Payload With Optional Attribute

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.

------------------------------
Yurii Yushchak
System Manager
Ericsson Inc.

Original Message:
Sent: Sep 04, 2024 04:04
From: Pritam Roy
Subject: How To Extend Error Response Payload With Optional Attribute

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"

}

------------------------------
Pritam Roy
Principal Solution Architect
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 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

Original Message:
Sent: Sep 05, 2024 06:22
From: Yurii Yushchak
Subject: How To Extend Error Response Payload With Optional Attribute

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.

------------------------------
Yurii Yushchak
System Manager
Ericsson Inc.

Original Message:
Sent: Sep 04, 2024 04:04
From: Pritam Roy
Subject: How To Extend Error Response Payload With Optional Attribute

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"

}

------------------------------
Pritam Roy
Principal Solution Architect
Tech Mahindra Limited
------------------------------

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"

}

------------------------------
Pritam Roy
Principal Solution Architect
Tech Mahindra Limited
------------------------------

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

Original Message:
Sent: Sep 04, 2024 04:04
From: Pritam Roy
Subject: How To Extend Error Response Payload With Optional Attribute

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"

}

------------------------------
Pritam Roy
Principal Solution Architect
Tech Mahindra Limited
------------------------------