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!

------------------------------
manuel pastor
Salesforce
------------------------------

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

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

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

------------------------------
manuel pastor
Salesforce
------------------------------

Original Message:
Sent: Jan 11, 2024 07:50
From: Jonathan Goldberg
Subject: Invoke Actions/Processes instead of CRUD Operations

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

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

This looks about right, Manuel. The task resource schema effectively defines the input and the output of the business operation that the task is intended to achieve.

------------------------------
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: Jan 11, 2024 09:29
From: manuel pastor
Subject: Invoke Actions/Processes instead of CRUD Operations

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

------------------------------
manuel pastor
Salesforce
------------------------------


Original Message:
Sent: Jan 11, 2024 07:50
From: Jonathan Goldberg
Subject: Invoke Actions/Processes instead of CRUD Operations

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

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

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.

------------------------------
Fazhong (David) Deng
OSSEra
------------------------------

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.

------------------------------
Olivier Arnaud
Orange
------------------------------

Original Message:
Sent: Jan 13, 2024 02:00
From: Fazhong (David) Deng
Subject: Invoke Actions/Processes instead of CRUD Operations

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.

------------------------------
Fazhong (David) Deng
OSSEra
------------------------------

Thanks Olivier for giving alternatives.

I think we should recognize that the process approach has some downsides, alongside its advantages:

• The contract between consumer and provider is weak, since the process flow API is completely generic.
• Not all tasks need full process management - especially tasks that are by nature synchronous (such as prepay balance management operations)
• The process layer adds latency

------------------------------
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: Jan 15, 2024 03:51
From: Olivier Arnaud
Subject: Invoke Actions/Processes instead of CRUD Operations

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.

------------------------------
Olivier Arnaud
Orange
------------------------------


Original Message:
Sent: Jan 13, 2024 02:00
From: Fazhong (David) Deng
Subject: Invoke Actions/Processes instead of CRUD Operations

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.

------------------------------
Fazhong (David) Deng
OSSEra