Open APIs

Expand all | Collapse all

Doubt around Optional meaning

  • 1.  Doubt around Optional meaning

    TM Forum Member
    Posted Aug 04, 2020 12:20
    Hello,

    I have a doubt around the use of Optional term in these APIs.
    Is it related to the usage of the element or the element implementation itself?

    Let's use the TMF620 Product Offering Element as an example.
    Within the Product Offering presented model, I'll use three sub-elements to describe the doubt:
    - statusReason: That is an attribute attached  directly to the Product Offering Element.
    - productOfferingTerm: That is an sub-element, attached to the Product Offering Element.
    - category: That is an sub-element, attached to the Product Offering Term.

    All of these elements are marked as Optional in the conformance profile document (TMF620B).
    By the way, category is even marked as an optional API resource element.

    It is clear that from usage perspective, all of these elements are optional in an instantiated product,
    meaning that, I can create and browse any Product Offering where these elements are not present.

    However, the key doubts here are:
    - Are they optional to be implemented?
    - Is the server obligated to accept and recognize them?
    - Is it OK if I decide not to implement these parameters/elements and, error out an incoming request that contains them
    (i.e.: we'll never silently ignore an unimplemented optional parameter but, we'll report that limitation)?

    Thanks and regards,






    ------------------------------
    Marcos Donato da Silva
    Ericsson Inc.
    ------------------------------


  • 2.  RE: Doubt around Optional meaning

    TM Forum Member
    Posted Aug 05, 2020 01:02
    Hi Marcos,
    In our adoption, optional attributes are documented with purpose, its usage etc. and are implemented in the API spec. These fields are not ignored just because it is marked as optional in TMF documentation. For consumers of the API, populating these attributes are optional. If consumers populate, servers will process the data as per the logic assigned to these attributes. In certain cases, the server may persist the optional attribute without any applying any further logic e.g. description, externalID etc.
    I am afraid if we are ignoring these optional attributes in the implementation, then we may end up in API version management nightmare when we get new use cases to use these optional attributes.
    Having said that, at times we found attributes with no immediate usage. In those circumstances also, we kept it as part of the API spec, but documented as no usage found in the provider context.



    ------------------------------
    Varun Nair
    Telstra Corporation
    Note: This is an opinion based on my research and not an official TMF response.
    ------------------------------



  • 3.  RE: Doubt around Optional meaning

    TM Forum Member
    Posted Aug 07, 2020 09:49
    Hi Vanun,
    Thanks.

    Actually, I've been working in some projects involving legacy API adaptation to TMF and the overall
    mindset is indeed to cover if not all, as many optional elements as possible but, this question
    around obligation to add an optional elements is recurrent.
    That's why I added this thread to sense how the forum sees this question.

    I also made an investigation over this Forum and over documentation and found no
    direct answer to the questino:
    If an element presented in the API is marked as optional and, is not there on the legacy API, is it:
    - Mandatory to implement it?
    - Mandatory to error it out if not implemented?

    Currently I'm working on TMF620 adaptation and, below text extracted from this API drive us to option-2:
    (..) If the POST request includes optional parameters as per the model resource definition
    that are not supported by the server, the server must reject the request (replying with a
    4xx error response) indicating the parameter not supported.(..)

    However, this is not possible to every Optional field as we have some of them being checked
    on the related CTKs.

    On top of that, this direction is also against what's there on the RFC2119, outlined in the
    TMF630 as the placeholder for OPTIONAL definition and meaning:

    5. MAY

    This word, or the adjective "OPTIONAL", mean that an item is truly optional. One vendor may choose to include the item because a particular marketplace requires it or because the vendor feels that it enhances the product while another vendor may omit the same item. An implementation which does not include a particular option MUST be prepared to interoperate with another implementation which does include the option, though perhaps with reduced functionality. In the same vein an implementation which does include a particular option MUST be prepared to interoperate with another implementation which does not include the option (except, of course, for the feature the option provides.)

    So I see a contradiction here because we should not error out a message that contains an
    element marked as optional, contradicting what's there on the TMF620 recommendation.

    In other words, even with minimum implementation, this gives the impression that we should
    add to our APIs all optional elements (as suggested on Varun's answer) or, in the worst case,
    silently ignore them.

    Therefore, it would be handy to understand at which degree this "optional" granularity goes:
    - On a resource level (e.g.: ProductCatalog entity is optional and, it's OK not to implement it).
    - On a sub-resource level (e.g.: ProductOfferingTerm entity is optional and, it's OK not to implement
      it and, error out a request with this element in the payload).
    - On an entity level (e.g.: statusReason attribute within the ProductOffering element is optional and,
      it's OK not to implement it and, error out a request with this attribute in the payload).

    At the ending, it would be good if we had an indication on whether a given sub-resource or attribute is
    mandatory to be implemented as we have on the resource level or, a directive on what's the minimum
    implementation required for an Optional field.

    Regards,


    ------------------------------
    Marcos Donato da Silva
    Ericsson Inc.
    ------------------------------



  • 4.  RE: Doubt around Optional meaning

    TM Forum Member
    Posted Aug 09, 2020 20:09
    Hi Marcos,
    My interpretation is that TMF does not ask for any obligation for using optional attributes and it is up to the individual organisation who adopts the TMF open APIs, to determine the implementation and usage of these optional attributes. If TMF wants implementation of any optional attributes in any API, they should be including those attributes in the conformance profile, so that it becomes a direction to implement these optional attributes. I am happy to be corrected here.
    In an org scenario where you are adopting these APIs for a multi-consumer <-> multi-provider integration, I think it is more important to align with the definition of MAY in RFC2119. 

    ------------------------------
    Varun Nair
    Telstra Corporation
    Note: This is an opinion based on my research and not an official TMF response.
    ------------------------------