Open APIs

 View Only
  • 1.  TMF630: Error Representation API Design Guidelines Part 1

    TM Forum Member
    Posted Jun 07, 2022 08:44
    Dear fellow OpenAPI enthusiasts,

    I am refering to REST API Design Guidelines Part 1, Version 4.0.2, from 13-Jan-2021.

    In the guide on page 19ff, chapter 3.4, there is a definition of an "Error Representation" in the body of the response with properties like code, reason, message and so on.

    On the other hand, there is RFC7807 from https://datatracker.ietf.org/doc/html/rfc7807, which also describes a somewhat similar Problem Details Object for HTTP APIs with completely different definition especially with different properties like type, title, status, detail  and so on.

    But the intentions of the object/representation are the same.

    Here's my question:
    What were the reasons not taking RFC7807 into account for the definition of the "Error Representation" in REST API Design Guidelines, chapter 3.4 ?

    Does anybody have some background information on this because we had a long discussion what definition is to be used and why are there 2 different definitions?
    Maybe I did not understand the texts of REST API Design Guidelines and the RFC or I miss a point.

    Any help or insight is appreciated.

    Kind regards
    Raoul Piechatzek

    ------------------------------
    Raoul Piechatzek
    Deutsche Telekom AG
    ------------------------------


  • 2.  RE: TMF630: Error Representation API Design Guidelines Part 1

    TM Forum Member
    Posted Jun 08, 2022 01:26
    Edited by Vance Shipley Jun 08, 2022 02:02
    On Jun 07, 2022 06:08 @Raoul Piechatzek wrote:
    > What were the reasons not taking RFC7807 into account for the definition of the "Error Representation" in REST API Design Guidelines, chapter 3.4 ?

    The easy answer is that RFC7807 is from 2016, well after TMF630 was first written!

    I did raise this issue in AP-2628 last year where my recommendations were:
    • Deprecate the old Error schema in v5 and align with RFC7807 in next version of TMF630.
    • Alternatively document both forms and encourage the use of RFC7807 going forward.

    You can have both coexisting however through use of the IANA registered media type "application/problem+json". The HTTP Content-Type header of a response may be used to explicitly indicate if the existing (application/json) or RFC7807 compliant problem details are used.

    The HTTP Accept header can be used to indicate that the client is prepared to accept an application/problem+json body of an RFC7807 response which allows introducing the IETF standard problem details in a backwards compatible way where the clients choose the format.​ This is what SigScale has chosen to do.

    ------------------------------
    Vance Shipley
    SigScale
    ------------------------------



  • 3.  RE: TMF630: Error Representation API Design Guidelines Part 1

    TM Forum Member
    Posted Jun 08, 2022 04:02
    Edited by Raoul Piechatzek Jun 08, 2022 04:04
    Hi Vance,

    thanks for the quick answer. That was helpful.

    As for the issue in AP-2628, is there a way to support the proposed change to the API Design Guidelines for the version 5, resp. the next version of the guidelines, so that it is more likely to be implementetd?

    BTW, is there a timeline for Version 5 or the next version of the API Design Guidelines?

    Kind regards


    ------------------------------
    Raoul Piechatzek
    Deutsche Telekom AG
    ------------------------------



  • 4.  RE: TMF630: Error Representation API Design Guidelines Part 1

    TM Forum Member
    Posted Jun 08, 2022 04:24
    Hi Raoul
    I've referred this issue to the Open API team, including people who are working on the guidelines.
    I'm afraid that I cannot promise anything, however.

    ------------------------------
    Jonathan Goldberg
    Amdocs Management Limited
    Any opinions and statements made by me on this forum are purely personal, and do not necessarily reflect the position of the TM Forum or my employer.
    ------------------------------