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

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