Open APIs

I have some experience with TMF APIs by now and I'm reading through TMF630 REST API Guidelines in more detail.

I stumbled upon 1.1. API Resource Archetypes. It provides TroubleTicket and ProductOrder as an example for for managed resources and ProductOfferingQualification as an example for task resources. Now, I'd argue that most (every?) Tasks are managed resources. Since I had a discussion recently that went a bit in a similar direction, a clarification would be nice of things that are managed resources, but not tasks.

I'd argue the that the following characteristics are probably a task and not only a manged resource

• if it has a state field, it's probably a task
• if you create it and expect it to be different after a given time, it's probably a task
• if you create and and expect the implicit creation/deletion/modification of another resource, it's probably a task

Managed resources, that are not tasks: productSpecification, agreement.

Now, since ProductOrder is resourced between collection and managed resource, but isn't mentioned again as an example for tasks, I wonder if i'm missing something.

Note that 1.1 mentions ProductOfferingQualification as an example for a Task, which is an exception to "should be a verb" from 8.1.

------------------------------
Omar Sood
Code monkey at conology
------------------------------

Hi Omar

I hear what you are saying, and on one level you could argue that all the <xxxx>Order entities are task entities. There's no doubt that they have state, and they manage the processing of other entities (product, service, resource). However, there is one important distinction, which is that an order is an entity that has business significance by itself.

Pure task entities are technical constructs that are needed to cover the fact that HTTP verbs (and hence REST operations) verbs are not useful for describing business operations (such as validating an address, topping up a usage bucket, etc.). So we define task resources and POST them to achieve the business operation. An Order is not like this and so I would not classify as a task operation.

Hope the distinction is clear.

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

Hi Jonathan,

That's an incredible useful baseline to differ between both concepts. Thank you a lot!

I have a follow up question. This may justify a separate question... One of the reasons I came across this question was a termination of a product between to providers in a B2B2C setting. To my understanding, since the product describes in a sense the agreement about resources and services at a location and both providers have their own copy of their view on the agreement. The offerer of these services gets a product order. This much is clear.

Now we discussed whether it makes sense to use a productOrder on orderer side as well in case it's terminated by the offerer for the validation and cleanup process on orderer side or if this would be an abuse. We also discussed if it's actually fair to say that both sides own a side of the product.

Since this is a process with business significance by itself (validate, escalate,inform customer), does this qualify as not a pure task? I'd say yes. And since it's a process related to a product removal, would productOrder fit here or should we rather introduce another task/managed entity?

------------------------------
Omar Sood
conology
------------------------------

Original Message:
Sent: Jun 11, 2024 09:49
From: Jonathan Goldberg
Subject: Would you consider productOrder a task resource?

Hi Omar

I hear what you are saying, and on one level you could argue that all the <xxxx>Order entities are task entities. There's no doubt that they have state, and they manage the processing of other entities (product, service, resource). However, there is one important distinction, which is that an order is an entity that has business significance by itself.

Pure task entities are technical constructs that are needed to cover the fact that HTTP verbs (and hence REST operations) verbs are not useful for describing business operations (such as validating an address, topping up a usage bucket, etc.). So we define task resources and POST them to achieve the business operation. An Order is not like this and so I would not classify as a task operation.

Hope the distinction is clear.

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

Hi Omar

Here's my thought. Let's say that you (Omar) are the end customer, BT is your provider, and BT uses CityFibre for the last mile at your location. So:

• You submit a Product Order (PO) to BT for broadband
• BT, as part of processing the service order (SO) decomposed from the PO, using their commercial relationship with CityFibre, submits a different PO to for connectivity
• CityFibre provisions the order and sends back the connectivity product to BT.
• BT's representation of the CityFibre product is a service in BT's service inventory, and is connected as an implementing service on the broadband product that BT gives to you.

Having said all this, there is a separate TMF working group discussing modeling and processes for wholesale fiber broadband, an example of a B2B2C setting.

I'm not sure exactly what their suggested direction is, but I'm going to bring this thread to their attention so that they can weigh in.

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

Original Message:
Sent: Jun 11, 2024 10:23
From: Omar Sood
Subject: Would you consider productOrder a task resource?

Hi Jonathan,

That's an incredible useful baseline to differ between both concepts. Thank you a lot!

I have a follow up question. This may justify a separate question... One of the reasons I came across this question was a termination of a product between to providers in a B2B2C setting. To my understanding, since the product describes in a sense the agreement about resources and services at a location and both providers have their own copy of their view on the agreement. The offerer of these services gets a product order. This much is clear.

Now we discussed whether it makes sense to use a productOrder on orderer side as well in case it's terminated by the offerer for the validation and cleanup process on orderer side or if this would be an abuse. We also discussed if it's actually fair to say that both sides own a side of the product.

Since this is a process with business significance by itself (validate, escalate,inform customer), does this qualify as not a pure task? I'd say yes. And since it's a process related to a product removal, would productOrder fit here or should we rather introduce another task/managed entity?

------------------------------
Omar Sood
conology
------------------------------


Original Message:
Sent: Jun 11, 2024 09:49
From: Jonathan Goldberg
Subject: Would you consider productOrder a task resource?

Hi Omar

I hear what you are saying, and on one level you could argue that all the <xxxx>Order entities are task entities. There's no doubt that they have state, and they manage the processing of other entities (product, service, resource). However, there is one important distinction, which is that an order is an entity that has business significance by itself.

Pure task entities are technical constructs that are needed to cover the fact that HTTP verbs (and hence REST operations) verbs are not useful for describing business operations (such as validating an address, topping up a usage bucket, etc.). So we define task resources and POST them to achieve the business operation. An Order is not like this and so I would not classify as a task operation.

Hope the distinction is clear.

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

Hi @Omar Sood, the project that is currently running is definitely looking to address some of the points you are raising in the post here both on what APIs are used and how to model the catalog for a B2B2x use case for fibre broadband. I would say that @Jonathan Goldberg's post eloquently describes the high level flow of resources and APIs that are being proposed to be used for that standard which  would say is still very much in the draft state. 

Focus within the project has so far been very much on the modelling of the interaction on a B2B basis between access provider and service provider however intended further scope to look at how the Product/Service/Resource catalog modelling and API interactions will work within a service provider are things on the backlog to tackle.

------------------------------
David Whitfield
PlatformX Communications (PXC)
------------------------------

Original Message:
Sent: Jun 26, 2024 08:47
From: Jonathan Goldberg
Subject: Would you consider productOrder a task resource?

Hi Omar

Here's my thought. Let's say that you (Omar) are the end customer, BT is your provider, and BT uses CityFibre for the last mile at your location. So:

• You submit a Product Order (PO) to BT for broadband
• BT, as part of processing the service order (SO) decomposed from the PO, using their commercial relationship with CityFibre, submits a different PO to for connectivity
• CityFibre provisions the order and sends back the connectivity product to BT.
• BT's representation of the CityFibre product is a service in BT's service inventory, and is connected as an implementing service on the broadband product that BT gives to you.

Having said all this, there is a separate TMF working group discussing modeling and processes for wholesale fiber broadband, an example of a B2B2C setting.

I'm not sure exactly what their suggested direction is, but I'm going to bring this thread to their attention so that they can weigh in.

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


Original Message:
Sent: Jun 11, 2024 10:23
From: Omar Sood
Subject: Would you consider productOrder a task resource?

Hi Jonathan,

That's an incredible useful baseline to differ between both concepts. Thank you a lot!

I have a follow up question. This may justify a separate question... One of the reasons I came across this question was a termination of a product between to providers in a B2B2C setting. To my understanding, since the product describes in a sense the agreement about resources and services at a location and both providers have their own copy of their view on the agreement. The offerer of these services gets a product order. This much is clear.

Now we discussed whether it makes sense to use a productOrder on orderer side as well in case it's terminated by the offerer for the validation and cleanup process on orderer side or if this would be an abuse. We also discussed if it's actually fair to say that both sides own a side of the product.

Since this is a process with business significance by itself (validate, escalate,inform customer), does this qualify as not a pure task? I'd say yes. And since it's a process related to a product removal, would productOrder fit here or should we rather introduce another task/managed entity?

------------------------------
Omar Sood
conology


Original Message:
Sent: Jun 11, 2024 09:49
From: Jonathan Goldberg
Subject: Would you consider productOrder a task resource?

Hi Omar

I hear what you are saying, and on one level you could argue that all the <xxxx>Order entities are task entities. There's no doubt that they have state, and they manage the processing of other entities (product, service, resource). However, there is one important distinction, which is that an order is an entity that has business significance by itself.

Pure task entities are technical constructs that are needed to cover the fact that HTTP verbs (and hence REST operations) verbs are not useful for describing business operations (such as validating an address, topping up a usage bucket, etc.). So we define task resources and POST them to achieve the business operation. An Order is not like this and so I would not classify as a task operation.

Hope the distinction is clear.

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

Hi,

I cannot put the right words because I'm not a techie but I like to use this example when talking to our developers:

the product catalogue contains an PO that has 2 POP:

• POP1 = a monthly price of €20
• POP2 = a 10% monthly discount because you're over 65 years

TMF620 will never, ever tell you the price to pay is €18 per month.

You can only do a GET operation to read the 2 prices and how one price alter the other. There is no computation.

==> TMF620 is a "resource API"

TMF679, on the contrary,  will calculate the product price and tell you that the price is €18 per month. Alternatively, it can also tell you the price is €20 minus a €2 discount.

you can only do a POST to calculate the "Product Price".

==> TMF679 is a "task API"

with this in mind, I consider that Cart, order etc can only be "resource API"

But I suggest you read this thread that offers nuances.

(again forgive the vocabulary)

My 2 cents

------------------------------
Kind regards,

Matthieu Hattab
Lyse Platform
------------------------------

Hi

I think the confusion comes from the fact TMF API were designed first to manage (create, read, update, delete) SID entities witout (to my knowledge) clearly standardizing what happens when the API is called appart from the pure entity management (CRUD). I imagine if we had done the way described below, we would have a clearer definition of our API :

• First define SID entities
• Then define functions and processes based on business requirements
• Then only at this step define API in order to describe communication between processes
  • Process A reads/updates entity Z managed by process B -> implies a "resource" API
  • Process A triggers process Y on process B and waits for the answer -> implies a "process/task" API
  • Process A has subscribed to events from process B -> "event" API

To come back to TMF622, for me, a /productOrder is a managed entity and doing a POST /productOrder just creates a productOrder entity. But in reality as we don't have yet a TASK like /submitProductOrder in the API, we use this POST /productOrder to trigger the process of validation of the order, but that's not standardized (to my knowledge). 

There is a TASK /cancelProductOrder that permits to trigger the process of cancelling an order. We could improve this API to have a /submitProductOrder and /amendProductOrder that would permit to trigger processes with real TASK operations intead of using POST and PATCH operation on a managed entity that should be done only at "database" level.

I hope that ongoing work in ODA components and IG1228 use cases will permit in following years to increase consistency between SID, Functions, Components and API.

------------------------------
olivier arnaud
Orange
------------------------------

Original Message:
Sent: Jun 26, 2024 06:34
From: Matthieu Hattab
Subject: Would you consider productOrder a task resource?

Hi,

I cannot put the right words because I'm not a techie but I like to use this example when talking to our developers:

the product catalogue contains an PO that has 2 POP:

• POP1 = a monthly price of €20
• POP2 = a 10% monthly discount because you're over 65 years

TMF620 will never, ever tell you the price to pay is €18 per month.

You can only do a GET operation to read the 2 prices and how one price alter the other. There is no computation.

==> TMF620 is a "resource API"

TMF679, on the contrary,  will calculate the product price and tell you that the price is €18 per month. Alternatively, it can also tell you the price is €20 minus a €2 discount.

you can only do a POST to calculate the "Product Price".

==> TMF679 is a "task API"

with this in mind, I consider that Cart, order etc can only be "resource API"

But I suggest you read this thread that offers nuances.

(again forgive the vocabulary)

My 2 cents

------------------------------
Kind regards,

Matthieu Hattab
Lyse Platform
------------------------------