Open APIs

 View Only

  • 1.  Design choice for TMF640 "collect" response – looking for feedback

    Posted 21 days ago

    Hi all,

    I would appreciate your feedback on a design choice we are currently evaluating regarding network data collection exposed at the CFS layer.

    Context

    In our OSS landscape, we have an application called XSO that exposes several APIs (e.g. TMF640, TMF641, TMF653, TMF645).
    At the CFS level, XSO provides a TMF640 Service Activation & Configuration interface, which:

    • Decomposes CFSs into RFSs (catalog- and rule-based)
    • Delegates activation to multiple NSALs (Network Service Activation Layers)
    • Each NSAL manages one or more RFSs and underlying Resources

    Objective

    We want to introduce a "collect" operation on the XSO TMF640 (CFS level), allowing applications to retrieve live/stored network information.

    Key characteristics:

    • The collect operation is cascaded to NSALs via their own TMF640 collect operations
    • Supports both synchronous and asynchronous modes (events via TMF688)
    • Uses TMF662 Entity Catalog to define the hierarchy of collectable entities (CFS → RFS)
    • EntitySpecifications are linked to ServiceSpecifications (TMF633) via entitySpecRelationship

    Request Structure (simplified example)

    The collect operation accepts a list of entities describing what data to retrieve:

    [
    {
        "name": "cpe.liveInfo",
        "characteristic": [
            {
                "name": "identifier",
				"valueType" : "object",
                "value": {
                    "type": "uniqueId",
                    "value": "uniqueId of a device"
                }
            }
        ],
        "entitySpecification": {
				"id": "id of entity spec collect.cpe.liveInfo"
		}
    }
]

    This is posted to TMF640: POST /service/{id}/collect

     

    Notes:

    • The request targets a specific CFS instance
    • Optional identifiers allow filtering (e.g. specific device vs all)
    • Based on the specification, the system determines which RFS/NSALs to invoke

    Design Question: What should the response look like?

    We are currently considering three options:

    Option 1 – Return a CFS enriched with collected data (relatedEntity by value)

    • Aggregate network data from NSALs and attach it to the CFS as relatedEntity (by value)

    Pros

    • Single call returns both:
      • Service inventory (CFS + RFS)
      • Collected network data

    Cons

    • TMF640 (v4/v5) Swaggers do not support relatedEntity by value
    • Data models suggest support, but Swagger definitions appear inconsistent
    • TMF702 (Resource Inventory) does not include relatedEntity
    • Would require extending both TMF640 and TMF702 APIs

    Option 2 – Return a list of collected entities

    • Response mirrors the request: list of entities (tree structure using entityRelationship) returned

    Pros

    • No API extension required
    • Clean and symmetric (entities in / entities out)

    Cons

    • No service inventory context (CFS/RFS) included in the response (could be through entities though...)

    Option 3 – Return a CFS with relatedEntity by reference

    • Store collected data in Entity Inventory (TMF703)
    • Return references (relatedEntity by ref) in the CFS

    Pros

    • No change required on TMF640
    • Aligns with persistence strategy (TMF703)

    Cons

    • Requires additional calls to retrieve actual data
    • Increased complexity for consumers
    • Still requires some extension on TMF702
    • Not our preferred option

    Question to the community

    Which option would you recommend, and why?

    In particular:

    • Have you faced similar challenges when exposing "collect" or telemetry-like operations?
    • How do you balance API purity (TMF compliance) vs usability (single-call vs multi-call patterns)?
    • Any best practices around using TMF662 / TMF703 in this context?

    Best regards,



    ------------------------------
    Frederic Thise
    Proximus SA
    ------------------------------


  • 2.  RE: Design choice for TMF640 "collect" response – looking for feedback

    Posted 20 days ago

    Hi Frederic,

    I notice that there is no mention of a TMF638 service inventory? Normally you would expect that the services would also be persisted (possibly off the TMF640 processes) in TMF638 - which would provide you with both a read interface, and notifications of changes.

    Have you considered that approach?



    ------------------------------
    Peter Eksteen
    Product Manager
    CIENA Blue Planet
    ------------------------------



  • 3.  RE: Design choice for TMF640 "collect" response – looking for feedback

    Posted 20 days ago

    Hi Peter,

    I have not described our full service portfolio but we are indeed using various TMF repository/inventory APIs like TMF638 and TMF639. When I mentioned that Option 1 would return the inventory part, it was from our ServiceInventory ;)

    Anyway TMF640 and TMF638 suffer from the same issue regarding relatedEntity property.

    Best regards,



    ------------------------------
    Frederic Thise
    Proximus SA
    ------------------------------

    Original Message


  • 4.  RE: Design choice for TMF640 "collect" response – looking for feedback

    Posted 20 days ago

    Hi Frederic,

    I get your point - but you should be aware that neither TMF640, nor TMF638 are intended as 'enrichment' API's.

    I would, if you intend to do this, implement your TMF640 Collect method, but I would persist the results in TMF638 - under relatedEntityRefOrValue (from TMF638 v4 and later specifications), returning success or failure on the operation (TMF640 is not supposed to 'return' much else).

    Then you can read the CFS details from TMF638 and in that manner retrieve the collected data.



    ------------------------------
    Peter Eksteen
    Product Manager
    CIENA Blue Planet
    ------------------------------

    Original Message


  • 5.  RE: Design choice for TMF640 "collect" response – looking for feedback

    Posted 20 days ago
    Edited by Frederic Thise 20 days ago

    Hi Peter,

    because of the its live (and potentially changing only at network level) aspect, the data returned by the NSALs (from the platforms which are non TMF) is "volatile" and not intended to be stored in TMF638. The related Entities that we store are permanent relationships towards other "external" TMF entities.

    Option 1 is not considered by us as similar to a GET operation on TMF640/638 and is more of a "hack" because it does not completely match the CFS stored in TMF638 (the relatedEntity part would be enhanced with the volatile network data)...

    Best regards,



    ------------------------------
    Frederic Thise
    Proximus SA
    ------------------------------

    Original Message


  • 6.  RE: Design choice for TMF640 "collect" response – looking for feedback

    Posted 14 days ago

    Hi all,

    Let me try to clarify our concern here, because I feel we are still not fully addressing the core issue.

    What we are facing is not fully about how to use relatedEntity, but about a structural gap in the OpenAPI modeling, especially when looking consistently across TMF640 and TMF702.

    In TMF640 (and similar APIs), EntityRefOrValue relies on a generic Entity base schema. Technically, Entity acts only as an envelope (Extensible + Addressable). However, in real-world implementations-and in examples from TMF703-when data is passed "by value," it is never just a generic blob. It is a concrete ManagedEntity with its own structure, meaning, and lifecycle.

    Because the OpenAPI/Swagger definition uses a generic type, we cannot automatically validate "by value" payloads. This forces interoperability to rely on implicit, out-of-band agreements between systems rather than the API contract itself. Is relatedEntity meant to be a reliable, contract-driven mechanism, or just a loose extensibility hook?

    So we end up with a mismatch where there is no way to validate "by value" payloads via Swagger/OpenAPI meaning that interoperability relies on implicit agreements between implementations, not on the API definition itself. From an architectural standpoint, this makes it very unclear whether "by value" in relatedEntity should be considered a reliable contract mechanism, or just a loose extensibility hook.

    On top of that, we feel that there is another inconsistency when we look at TMF640 vs TMF702 together. TMF640 provides relatedEntity to carry secondary/context entities (by ref or by value), while TMF702 does not offer an equivalent construct. This is difficult to reconcile, because in practice TMF640 and TMF702 are used together, and we would expect a consistent way to represent and exchange those secondary entities across both APIs. Today, this leads to asymmetric payloads and forces implementations to externalize or duplicate logic.

    So there are really two linked questions behind this discussion:

    • Is the fact that EntityRefOrValue relies on a generic Entity (with no strong typing) a deliberate long-term design choice, even though actual usage clearly involves structured managed objects?
    • And is the absence of aligned constructs (like relatedEntity) in APIs such as TMF702 also intentional, or simply a gap in consistency between APIs that are expected to be used together meaning that it'll be managed in a (near) future? 

    Depending on the answer, the architectural impact is quite significant. If this is expected to evolve, then using "by value" via relatedEntity becomes a safe and forward-looking approach (and we'll perform the extension to cover it). If not, then we should probably avoid relying on it for anything requiring strong typing, and instead enforce our own contracts outside of TMF APIs.

    It would really help to get a clear and explicit position from TMF API owners on this point - whether this is an intentional design trade-off that will remain as-is, or something that is expected to be addressed in upcoming versions.

    This will directly drive how we design and align our usage of these APIs.

    We look forward to your guidance on this.



    ------------------------------
    Joel Deribreux
    Proximus SA
    ------------------------------

    Original Message


Related Content