Open APIs

 View Only

  • 1.  TASK Resource example

    Posted Nov 04, 2018 20:44
    Hello, 
     I have a requirement where I need to do an add/delete/update as part of single call. How can i achieve the same ? 
    I read "TMF630_REST_API_Design_Guidelines_Part_1_R14.5.1" and "TMF663_Shopping_Cart_API_REST_Specification_R18.0.0" and it mentions about Task resources to expose complex operations not easily decomposable to CRUD Entity based operations.
    Can you give me an example of how to implement this task resource ?

     - Avinash

    ------------------------------
    Avinash Kumar
    Infosys Ltd.
    ------------------------------


  • 2.  RE: TASK Resource example

    TM Forum Member
    Posted Nov 05, 2018 02:21

    Hi Avinash
    I am assuming in this reply that you want to add/delete/modify multiple managed (top-level) resources. If you are referring to contained (sub-) resources within a top-level resource (e.g. adding and removing RelatedParty refs to an Account), then you would use the PATCH verb as described in the design guidelines.

    There is a good example of a task resource in the Address Management API https://projects.tmforum.org/wiki/download/attachments/90514876/TMF675_GeographicLocationManagement_API_REST_Specification_R17.5.0.pdf?api=v2
    You can see that the designer created a task resource GeographicAddressValidation that deals with validating the address. This resource includes the actual address to be validated and structures that show the outcome of the validation.
    For your situation, you would create a task resource called something like <Entity>Manipulation (sorry can't think of a better name). This resource would have links to the entities you wish to manipulate, probably three named lists <entity>ToAdd, <entity>ToModify, <entity>ToDelete. The resource would also have structures that indicate the success or failure of the operation.
    To execute the task you would POST the task resource after filling out the entity lists in memory.
    If the task is synchronous the return from the POST would include the success or failure information, while if the task is asynchronous the return would include some interim status and some ID/HREF information so that the consumer can keep track of the task; you might also consider setting up notification for the asynchronous case.
    Note that if you are managing multiple entities in a single API operation you need to consider the transaction semantics if there is a failure, depending on the business you could do any of the following (and more), and you would need to make this information available in the return structure:

    • Stop processing at the first failure and rollback the successes that happened until then
    • Stop processing at the first failure but keep the successes
    • Process until the task is complete, so there could be multiple failures and multiple successes
    Hope it helps.

    ------------------------------
    Jonathan Goldberg
    Amdocs Management Limited
    ------------------------------

    Original Message


  • 3.  RE: TASK Resource example

    TM Forum Member
    Posted Nov 05, 2018 03:31
    Hi
    We are using the naming convention of task to start with Verb. For example ../shoppingCart/{shopppingCartId}/empty
    Or validate etc.. in geographicAddressValidation the name do not start with verb. I think we need to clarify the RES Design Guideline. 
    See quote  from the guideline Part 1:"
     "A TASK resource name is a verb representing the task to be executed. TASK creation may result in the creation of a number of related resources or other tasks.  E.g validate, check, heal, migrate, clear, close, transfer..etc

    ------------------------------
    Jacob Avraham
    Amdocs Management Limited
    ------------------------------

    Original Message