Open APIs

Hi all, 

I'm relatively new to TMF (very much a beginner) and I have a general question around extending the APIs.

After getting some help from the message boards and going through TMF630 a couple of times, there does not seem to be a limit of how often someone can extend an API. If I have a requirement that cannot be met directly using the existing structures, it seems that I can just add a new attributes to meet the requirement. Provided the API meets the minimum conformance requirements and the attributes that have been added do not invalidate the core characteristics of the API, the API can be signed off as TMF compliant.

Is it correct to say it's completly up to the designer to extend an API as they see fit by adding new attributes in order to fulfil bespoke requirements so long as they do not invalidate the API by doing so?

My concerns related to reusability. If an API is extended with 50 new attributes, it may not be especially usable by consuming systems which goes against the entire purpose of TMF. To be clear, I'm not saying I want or need to alter the documented resources massively - my only reqirement is to return limited additional information in GET requests.

Thank you in advance,

------------------------------
Thomas O Donnell
MDS Global Ltd
------------------------------

Hi Thomas

It really does depend on what your intentions are in extending the API contract. TMF regards the standard Open API assets as an aid to easier integration in the service provider IT environment. So that all parties agree on what is meant by Customer, Product, etc.

However, the bar for passing the conformance tests and getting certification is, for most APIs, relatively low. Therefore, having a conformant implementation is not necessarily a guarantee for seamless integration.

If there is a clear business need for an extension that can be valuable for the industry, you could consider contributing it back to the Open API project.

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

Thanks Jonathan,

The original query was more a general musing - you provided some guidance for my specific requirements in a different thread (Characteristics Schema - Value Type | Open APIs (tmforum.org))

Having done a bit more reading since, I think TMF717 meets my extension requirement - I'll probably just extend TMF629 as a stopgap until TMF717 is finalised.

Regards,

------------------------------
Thomas O Donnell
MDS Global Ltd
------------------------------

Original Message:
Sent: Mar 20, 2023 07:08
From: Jonathan Goldberg
Subject: Extending TMF APIs

Hi Thomas

It really does depend on what your intentions are in extending the API contract. TMF regards the standard Open API assets as an aid to easier integration in the service provider IT environment. So that all parties agree on what is meant by Customer, Product, etc.

However, the bar for passing the conformance tests and getting certification is, for most APIs, relatively low. Therefore, having a conformant implementation is not necessarily a guarantee for seamless integration.

If there is a clear business need for an extension that can be valuable for the industry, you could consider contributing it back to the Open API project.

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

You're basically right, but with an important caveat. TMF APIs are designed to be extensible, and the specs intentionally allow providers to add attributes as long as mandatory fields, behaviors, and semantics stay intact. From a pure conformance perspective, adding custom attributes does not break compliance if you follow the extension rules. However, TMF compliance is only the floor, not the goal. Over-extending an API absolutely hurts reuse and interoperability. Best practice is to extend sparingly, keep extensions optional, and group them clearly, often via relatedParty, characteristics, or a well-named extension object. If you need lots of extra data, that's usually a sign the data belongs in another resource or API, not bolted onto an existing one.

------------------------------
Alia Waite
TO BE VERIFIED
------------------------------

You're broadly right, but with a few important caveats.

TMF APIs are intentionally extensible. You are allowed to add attributes as long as you don't break the core resource semantics or mandatory fields. That's how TMF expects vendors to handle gaps and local needs.

That said, "can" and "should" are different things. Heavy extension quickly hurts reuse and interoperability. If a consumer needs to understand 50 bespoke fields, you've effectively created a private API website with a TMF wrapper.

Best practice is to keep extensions minimal, clearly namespaced, and optional. If the data is niche, consider relatedParty, characteristics, or a side API instead of bloating the core resource. If many projects need the same extension, that's a signal it belongs back with TMF.

So yes, it's designer-driven. But restraint is what keeps it useful.

------------------------------
Alia Waite
TO BE VERIFIED
------------------------------