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.
------------------------------
Original Message:
Sent: Aug 05, 2020 01:01
From: Varun Nair
Subject: Doubt around Optional meaning
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.
Original Message:
Sent: Aug 04, 2020 12:19
From: Marcos Donato da Silva
Subject: Doubt around Optional meaning
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.
------------------------------