Open APIs

Hi everyone,

Im looking for a way to use TMF666 not for typical CRUD operations, but to invoke a specific producer API that triggers a process in the system. Lets say that there are 3 scenarios once an Account is already existing: Terminate, Suspend, Cancel Termination....

Ideally I think that to cover these scenarios, the PATCH method should be used, letting the producer identify which internal process to trigger depending on the updated value in the payload. But in our case, the producer has 3 different endpoints with different payloads for each of the operations. My idea is to use a unique API, and depending on the action to perform, enforce the applicable schema, like when creating an account, we load the BillingAccount_Create schema.

Like for example: POST /tmf-api/accountManagement/v4/billingAccount/{id}:Terminate (this case will use the specific schema defined for the Terminate action...

There are couple of problems with this notation, like passing an id when using a POST, so I don't know if my reasoning would be something to even consider at all...

Thanks for sharing your point of view!

Hi Manuel

You are looking for a way to express business operations that fall outside the CRUD scope. And since we are using the REST syntax, we are limited in the number of verbs that we have at our disposal, and how they can be shoehorned to have specific business semantics.

TMF Open API uses the Task Resource pattern, documented in TMF630 design guidelines. You can find examples in many APIs, such as CancelProductOrder in TMF622, or all the balance management operations in Prepay Balance Management. The idea is that the task resource is posted, and this executes the task, which might be equivalent to a synchronous operation, or could be asynchronous.

Hope it helps

Hi everyone,

Im looking for a way to use TMF666 not for typical CRUD operations, but to invoke a specific producer API that triggers a process in the system. Lets say that there are 3 scenarios once an Account is already existing: Terminate, Suspend, Cancel Termination....

Ideally I think that to cover these scenarios, the PATCH method should be used, letting the producer identify which internal process to trigger depending on the updated value in the payload. But in our case, the producer has 3 different endpoints with different payloads for each of the operations. My idea is to use a unique API, and depending on the action to perform, enforce the applicable schema, like when creating an account, we load the BillingAccount_Create schema.

Like for example: POST /tmf-api/accountManagement/v4/billingAccount/{id}:Terminate (this case will use the specific schema defined for the Terminate action...

There are couple of problems with this notation, like passing an id when using a POST, so I don't know if my reasoning would be something to even consider at all...

Thanks for sharing your point of view!

Indeed! 

So in my case, it would be an extension to the standard, by adding the operation you need to support; having a new path with its allowed methods, which in my case would be POST /tmf-api/accountManagement/v4/billingAccount/Terminate_Account where in the body we would pass the id of the Account we would like to terminate, plus all other fields that we define for the schema that supports the path: 

New Path:

/Terminate_Account

"post": {
  "operationId": "createTerminate_Account",
  "summary": "Creates a Terminate Account",
  "description": "This operation creates a terminate account entity/task.",
 
  "parameters": [
    {
      "name": "TerminateAccount",
      "description": "......",
      "required": true,
       "schema": {
  "$ref": "#/definitions/Terminate_Account_Create"
},

etc.

If Im not mistaken that is how is properly done....

Hi Manuel

You are looking for a way to express business operations that fall outside the CRUD scope. And since we are using the REST syntax, we are limited in the number of verbs that we have at our disposal, and how they can be shoehorned to have specific business semantics.

TMF Open API uses the Task Resource pattern, documented in TMF630 design guidelines. You can find examples in many APIs, such as CancelProductOrder in TMF622, or all the balance management operations in Prepay Balance Management. The idea is that the task resource is posted, and this executes the task, which might be equivalent to a synchronous operation, or could be asynchronous.

Hope it helps

Hi everyone,

Im looking for a way to use TMF666 not for typical CRUD operations, but to invoke a specific producer API that triggers a process in the system. Lets say that there are 3 scenarios once an Account is already existing: Terminate, Suspend, Cancel Termination....

Ideally I think that to cover these scenarios, the PATCH method should be used, letting the producer identify which internal process to trigger depending on the updated value in the payload. But in our case, the producer has 3 different endpoints with different payloads for each of the operations. My idea is to use a unique API, and depending on the action to perform, enforce the applicable schema, like when creating an account, we load the BillingAccount_Create schema.

Like for example: POST /tmf-api/accountManagement/v4/billingAccount/{id}:Terminate (this case will use the specific schema defined for the Terminate action...

There are couple of problems with this notation, like passing an id when using a POST, so I don't know if my reasoning would be something to even consider at all...

Thanks for sharing your point of view!

Hi everyone,

Im looking for a way to use TMF666 not for typical CRUD operations, but to invoke a specific producer API that triggers a process in the system. Lets say that there are 3 scenarios once an Account is already existing: Terminate, Suspend, Cancel Termination....

Ideally I think that to cover these scenarios, the PATCH method should be used, letting the producer identify which internal process to trigger depending on the updated value in the payload. But in our case, the producer has 3 different endpoints with different payloads for each of the operations. My idea is to use a unique API, and depending on the action to perform, enforce the applicable schema, like when creating an account, we load the BillingAccount_Create schema.

Like for example: POST /tmf-api/accountManagement/v4/billingAccount/{id}:Terminate (this case will use the specific schema defined for the Terminate action...

There are couple of problems with this notation, like passing an id when using a POST, so I don't know if my reasoning would be something to even consider at all...

Thanks for sharing your point of view!

Generally, CRUD are used in authorization on data. For operations, there would be authorization on execution. When we design authorization in our system, we do support it for things such as a process flow (for example, a healing process flow, configuration process flow, or activation flow, etc.) However, it is hard if it is not impossible to implement it in REST.

Hi everyone,

Im looking for a way to use TMF666 not for typical CRUD operations, but to invoke a specific producer API that triggers a process in the system. Lets say that there are 3 scenarios once an Account is already existing: Terminate, Suspend, Cancel Termination....

Ideally I think that to cover these scenarios, the PATCH method should be used, letting the producer identify which internal process to trigger depending on the updated value in the payload. But in our case, the producer has 3 different endpoints with different payloads for each of the operations. My idea is to use a unique API, and depending on the action to perform, enforce the applicable schema, like when creating an account, we load the BillingAccount_Create schema.

Like for example: POST /tmf-api/accountManagement/v4/billingAccount/{id}:Terminate (this case will use the specific schema defined for the Terminate action...

There are couple of problems with this notation, like passing an id when using a POST, so I don't know if my reasoning would be something to even consider at all...

Thanks for sharing your point of view!

An alternative to custom Task operations is to model processes on the component and use TMF701 ProcessFlow to trigger them. The component can itself do the create, update, delete operations on the data it is responsible for. You can have a look at TMFS001 Use Case: New Party – Create your own account v4.0.2 – TM Forum for examples of how to use this API.

Generally, CRUD are used in authorization on data. For operations, there would be authorization on execution. When we design authorization in our system, we do support it for things such as a process flow (for example, a healing process flow, configuration process flow, or activation flow, etc.) However, it is hard if it is not impossible to implement it in REST.

Hi everyone,

Im looking for a way to use TMF666 not for typical CRUD operations, but to invoke a specific producer API that triggers a process in the system. Lets say that there are 3 scenarios once an Account is already existing: Terminate, Suspend, Cancel Termination....

Ideally I think that to cover these scenarios, the PATCH method should be used, letting the producer identify which internal process to trigger depending on the updated value in the payload. But in our case, the producer has 3 different endpoints with different payloads for each of the operations. My idea is to use a unique API, and depending on the action to perform, enforce the applicable schema, like when creating an account, we load the BillingAccount_Create schema.

Like for example: POST /tmf-api/accountManagement/v4/billingAccount/{id}:Terminate (this case will use the specific schema defined for the Terminate action...

There are couple of problems with this notation, like passing an id when using a POST, so I don't know if my reasoning would be something to even consider at all...

Thanks for sharing your point of view!