Open APIs

 View Only
  • 1.  Swagger Files Not Updated

    Posted Dec 28, 2022 04:49
    Hello,

    During implementation for Customer Management open API, I found that swagger files generated models are not matching SID model.

    Swagger files is based on version 19.0.1 while SID model is version 22.0.0

    Any plans to update the swagger files soon?

    if not, is there any source to identify the needed updates to match SID model 22.0.0?


    ------------------------------
    Ahmed Elbanna
    SEGMA COM
    ------------------------------


  • 2.  RE: Swagger Files Not Updated

    TM Forum Member
    Posted Dec 28, 2022 14:55
    Hi Ahmed

    Thanks for your alertness.

    Firstly, I want to clarify that there is no direct and one-to-one correspondence between the models in the SID and the Open API. As a general rule, of course, the major entities in the two models are aligned. However there are many differences, due to mapping work instructions and other factors; a few examples:
    • The SID is completely normalized, while we allow Open API model to have non-normalized attributes where this will make the API easier to use
    • The SID has deep class hierarchies - we try to avoid these in the Open API where possible, again for ease of use. Compare ProductOfferingPrice in the Open API, a single class, against the corresponding SID deep class hierarchy with different classes for different price types (recurring, one-time, etc.).
    • The SID is a conceptual model and as such is fairly light on attributes. The Open API model is used in implementation and has many more attributes, which appear as a result of real-life experience of implementing APIs
    Specifically for Customer Management, can you say what discrepancies you found, and explain what you think needs to be fixed and why.

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



  • 3.  RE: Swagger Files Not Updated

    Posted Dec 29, 2022 03:32
    Hello Jonathan,

    Many thanks for your clarification.

    I understand that there is no direct one-to-one mapping between models in the SID and the Open API, which raised below question for me:
    - Wouldn't it be easier for the implementers to have the same models for SID and API? this way the implementers wouldn't have to worry about manually mapping fields from SID to API. after all the consumers will follow the API contract even if it is more complicated.
    - If I am looking to certify Customer Management Open API, should I follow the existing API documents and manually map all required fields from SID to API if needed? or am I allowed to introduce the new models from SID to API swaggers.

    Regarding customer management API
    Let's take the example for creating customer, the mandatory fields require to have name and engagedParty which I think should be corrected to relatedParty.
    So, if I have the engagedParty of type Individual I will have to add required fields of Individual which are givenName and familyName, at this point referring back to Individual in SID, you don't have these attributes, you have object of type IndividualName which carry the attributes for Individual with different names (givenNames, familyNames).
    which forces me to create manual mapping and restrict using of Spring JPA for example.

    I would like to thank you in advance, and I wonder if there are running projects that could help me have better understanding for the implementation of Open APIs.

    ------------------------------
    Ahmed Elbanna
    SEGMA COM
    ------------------------------



  • 4.  RE: Swagger Files Not Updated

    TM Forum Member
    Posted Dec 29, 2022 15:00
    Hi Ahmed

    I explained reasons why the Open API model differs from the SID. If you are looking to certify Customer Management API you need to implement the API as described in the user guide and the conformance profile document. The SID is completely irrelevant to API implementation and conformance.

    You are at liberty to extend the API model with additional fields, as described in TMF630 design guidelines. Be aware, however, that the conformance test kit will probably fail if your extensions are marked as mandatory, since the CTK won't supply values for those fields at input.

    Now to explain engagedParty - Customer is a special case of PartyRole. The engagedParty attribute in PartyRole (and so in Customer) represents the party (individual or organization) that is playing the role. A party may of course play multiple roles, but there cannot be a party role without a party. Hence engagedParty is mandatory, and it is a reference to an existing party.

    I explained in your other post that it would be better to create a dedicated task operation to allow a full customer setup with multiple entities provided at the same time. In the model for this task operation you would supply the full schemas for all the involved entities (customer, organization, accounts, etc.).

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