Open APIs

 View Only
Back to discussions
Expand all | Collapse all

TMF629 Documentation vs Conformance Inconsistency

  • 1.  TMF629 Documentation vs Conformance Inconsistency

    Posted Oct 14, 2021 11:45
    I am currently working in the implementation of TMF629 OpenAPI using the official documentation (TMF629_Customer_Management_Specification_API_REST_R19.0.0.pdf) from the following page https://projects.tmforum.org/wiki/display/API/Open+API+Table, but I am facing problems when running the CTK (Conformant Toolkit).

    The OpenAPI swagger file clearly specifies the following two mandatory params:
    [ "engagedParty", "name" ],
    This makes sense according to the documentation diagrams and also to the documentation Create Customer section which specifies clearly which are the two mandatory fields:

    But in that same documentation just a few lines after it show an example request body which does not fulfill the mandatory fields:

    As you can see there "name" and "relatedParty" are used as a sample request instead of "name" and "engagedParty", also that same request body is the one used by the CTK when running the Customer postman calls to create a customer.

    My API is failing because it needs to have an engagedParty instead of relatedParty.

    Has anybody faced this kind of problem, and if so how should I proceed? how can I get the CTK changed so that it follows the documentation?

    Thanks

    ------------------------------
    Eduardo Sanchez
    MATRIXX Software
    ------------------------------


  • 2.  RE: TMF629 Documentation vs Conformance Inconsistency

    Posted Oct 15, 2021 14:18
    Hi Eduardo,

        I agree with you about the inconsistency in the documentation, but in this case I believe that the inconsistency is in the examples, which has relatedParty instead of  engagedParty, but when talking about the CTK,  the mandatory attributes are engagedParty and name as you can see on the schema, then in this case it seems that there is no need to change it.



    Best regards,
    Adinan Sousa

    ------------------------------
    Adinan Sousa
    Ericsson Inc.
    ------------------------------



  • 3.  RE: TMF629 Documentation vs Conformance Inconsistency

    Posted Oct 19, 2021 06:48
    Hi Adinan,

    You are right, the problem was not caused by the relatedParty since the CTK-Customer-4.0.0 postman collection was sending engagedParty.

    The problem is on a header, the swagger.json spec available in the TMF website and used to generate the OpenAPI server specifies that the server should produce and consume "application/json;charset=utf-8":
    consumes: [
   "application/json;charset=utf-8"
],
produces: [
   "application/json;charset=utf-8"
],​
    Therefor the server created using this OpenAPI spec produces and consumes "application/json;charset=utf-8" but then the CTK is not sending that format, instead it sends: "application/json" which is not interpreted as the same thing:
    "request": {
   "method": "POST",
   "header": [
     {
	"key": "Accept",
	"value": "application/json"
     },...​

    When the CTK request with header Accept: "application/json" is received the server responds with a "406 Not Acceptable" error response.
    So there are two options, manually change the swagger.json to:

    consumes: [
   "application/json"
],
produces: [
   "application/json"
],​

    or change the conformance toolkit to send "application/json;charset=utf-8", both of these resources are produced and released by TMF and ideally should not be changed, so I am not sure how to proceed.

    Any suggestions?




    ------------------------------
    Eduardo Sanchez
    MATRIXX Software
    ------------------------------

    Original Message


  • 4.  RE: TMF629 Documentation vs Conformance Inconsistency

    Posted Oct 20, 2021 10:27
    Hi Eduardo,

        Would not be redundant to designate the encoding (utf-8), since that utf-8 is the default encoding value, then I am not sure why the server responds with 406 error in this case, because at the end application/json and application/json; charset=utf-8 would be the same in this case .

    Best regards,
    Adinan Sousa


    ------------------------------
    Adinan Sousa
    Ericsson Inc.
    ------------------------------

    Original Message


  • 5.  RE: TMF629 Documentation vs Conformance Inconsistency

    Posted Oct 25, 2021 09:36
    Hi all
    engagedParty is definitely mandatory in Customer (and PartyRole) creation, it represents the party who is playing the Customer (or PartyRole).
    However there was a defect in older versions in this area, and it's possible that when it was fixed they didn't update the examples.
    Regarding the charset, I've sent a mail to the TM Forum focals for CTKs asking them to take a look.
    Hope it helps.

    ------------------------------
    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.
    ------------------------------

    Original Message


  • 6.  RE: TMF629 Documentation vs Conformance Inconsistency

    Posted Oct 27, 2021 04:11
    Thanks Jonathan. How can I have a follow up with the TM Forum focals for CTKs so that I am aware when the CTK is updated or any other resolution.

    ------------------------------
    Eduardo Sanchez
    MATRIXX Software
    ------------------------------

    Original Message


  • 7.  RE: TMF629 Documentation vs Conformance Inconsistency

    Posted Oct 27, 2021 04:35
    Hi Eduardo
    The most obvious step to take would be to put a Confluence watch on the Open API table pages. This way you get email notification when anything changes.
    • The main table here
    • The early access here
    To add a watch, simply click the eye icon (labeled Watch) at the top right of the page.
    • The main table here
    • The early access here
    Hope it helps

    ------------------------------
    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.
    ------------------------------

    Original Message


  • 8.  RE: TMF629 Documentation vs Conformance Inconsistency

    Posted Oct 27, 2021 05:25
    Thanks!

    ------------------------------
    Eduardo Sanchez
    MATRIXX Software
    ------------------------------

    Original Message


  • 9.  RE: TMF629 Documentation vs Conformance Inconsistency

    Posted Oct 26, 2021 21:28

    In an Accept or Content-Type HTTP header these are equivalent:

    application/json

    application/json;charset=utf-8

    The MIME type for JSON is provided in RFC4627 where the default encoding is defined as UTF-8.

    The TM Forum should however be consistent in their use to avoid the sort of trouble you experienced.



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

    Original Message


  • 10.  RE: TMF629 Documentation vs Conformance Inconsistency

    Posted Jan 20, 2022 09:00
    Edited by Marlon Almazan Jan 26, 2022 12:21
    Hi all

    The current version of the Conformance Profile document for TMF629 shows the attribute engagedParty as Optional. There is a comment "The sub-property
    @referredType is mandatory" but this is still a bit confusing and inconsistent with the main specification document.



    Thanks for clarifying.

    Regards,

    ------------------------------
    Leo Hodgson
    Cerillion Technologies Limited
    ------------------------------

    Original Message


Related Content