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.

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

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.

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

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.

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?

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.

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

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,

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

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

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