Open APIs

Hello,

I am not clear about how events in TMF688 are versioned.

Scenario:
A resource server decides to upgrade his resource model with breaking changes supporting still the old version in parallel for a transition period for old consumers.
In case of API access a consumer is able to choose via URI versioning properly between the 2 major versions of provided API spec.

In TMF630,Part1,Chapter 11.1 following is stated "... The versioning is applied uniformly to all the entities under a versioned API. That is, it is assumed that
entities under the management scope of the API are all aligned with the same version ..."

Question: What is the concept in the event management TMF688 to indicate a clear versioning for consumers/listeners?

Follow-up Question:
Usually a consumer does provide a single technical endpoint for receiving all events. So, URI versioning does not work, a consumer needs to identify during receiving which version the payload refers to.

Regards
Andreas Lobenwein
Telefonica Germany GmbH & Co. OHG

Hi Andreas

These are great questions, and it does seem that the Open API guidelines did not cover this. BTW this is not related specifically to the event API TMF688, but rather to any message-mediated asynchronous interaction, such as the older hub subscribe mechanism, or even the very new async APIs that have started to be published on the beta Open API table.

There are many scenarios to consider here. Just one example - a message format was changed in a non-compatible way, say by removing a property. There will be some (new) consumers that will be able to read and process the new message version, while there will be other (old) consumers that will not be able to deal with the new version. The implication is that the message provider needs to write the message in both formats, and consumers need to be written in such a way that they are able to extract and process the version of the message that they support.

A full treatment would need a detailed discussion within the Open API team, so I plan to raise an issue for this discussion. Due to DTW I cannot imagine anything will happen immediately.

Hello,

I am not clear about how events in TMF688 are versioned.

Scenario:
A resource server decides to upgrade his resource model with breaking changes supporting still the old version in parallel for a transition period for old consumers.
In case of API access a consumer is able to choose via URI versioning properly between the 2 major versions of provided API spec.

In TMF630,Part1,Chapter 11.1 following is stated "... The versioning is applied uniformly to all the entities under a versioned API. That is, it is assumed that
entities under the management scope of the API are all aligned with the same version ..."

Question: What is the concept in the event management TMF688 to indicate a clear versioning for consumers/listeners?

Follow-up Question:
Usually a consumer does provide a single technical endpoint for receiving all events. So, URI versioning does not work, a consumer needs to identify during receiving which version the payload refers to.

Regards
Andreas Lobenwein
Telefonica Germany GmbH & Co. OHG

Hi Jonathan,

thx for looking into this question.

What do you think about using the @schemaLocation attribute in TMF688 Event Structure for indicating the "version" implicitly by including it into the URI path of the location value?
For me it looks TMF compliant and fitting to TMF intentions, doesn't it?

Proposal e.g.
POST /client/listener
{
"@schemaLocation": "./schema-registry/API-CONTEXT-OF-EVENT/v1/event-schema.json"
"eventType": "EVENT_TYPE"
"event": {
EVENT BODY
},
}

POST /client/listener
{
"@schemaLocation": "./schema-registry/API-CONTEXT-OF-EVENT/v2/event-schema.json"
"eventType": "EVENT_TYPE"
"event": {
EVENT BODY
},
}

A more customized/proprietary variant is to add into event analyticCharacteristic a version indicator key-value pair.
I tend to the @schemaLocation.

Regards
Andreas.

Hi Andreas

These are great questions, and it does seem that the Open API guidelines did not cover this. BTW this is not related specifically to the event API TMF688, but rather to any message-mediated asynchronous interaction, such as the older hub subscribe mechanism, or even the very new async APIs that have started to be published on the beta Open API table.

There are many scenarios to consider here. Just one example - a message format was changed in a non-compatible way, say by removing a property. There will be some (new) consumers that will be able to read and process the new message version, while there will be other (old) consumers that will not be able to deal with the new version. The implication is that the message provider needs to write the message in both formats, and consumers need to be written in such a way that they are able to extract and process the version of the message that they support.

A full treatment would need a detailed discussion within the Open API team, so I plan to raise an issue for this discussion. Due to DTW I cannot imagine anything will happen immediately.

Hello,

I am not clear about how events in TMF688 are versioned.

Scenario:
A resource server decides to upgrade his resource model with breaking changes supporting still the old version in parallel for a transition period for old consumers.
In case of API access a consumer is able to choose via URI versioning properly between the 2 major versions of provided API spec.

In TMF630,Part1,Chapter 11.1 following is stated "... The versioning is applied uniformly to all the entities under a versioned API. That is, it is assumed that
entities under the management scope of the API are all aligned with the same version ..."

Question: What is the concept in the event management TMF688 to indicate a clear versioning for consumers/listeners?

Follow-up Question:
Usually a consumer does provide a single technical endpoint for receiving all events. So, URI versioning does not work, a consumer needs to identify during receiving which version the payload refers to.

Regards
Andreas Lobenwein
Telefonica Germany GmbH & Co. OHG