Open APIs

Expand all | Collapse all

Query Complex Types: Array

  • 1.  Query Complex Types: Array

    TM Forum Member
    Posted Jul 21, 2017 07:01
    Edited by Vance Shipley Aug 01, 2017 01:11
    In the section on query and filtering TMF630 REST Guidelines states:
    Complex attribute value type may be filtered using a "." notation.
                         [{attributeName.attributeName}={attributeValue}&*]

    So given a collection of objects:
    [
         ...
         {

              "id": 123,
              "foo":
                   {
                        "bar": 42
                   }
         }
         ...
    ]


    We can select it using: ?foo.bar=42

    Currently we are using TMF635 Usage Management where the attribute usageCharacteristic is an array of name/value objects:
    {
         "id": 456,
         ...
         "usageCharacteristic":
              [
                   ...
                   {
                        "name": "poolNumber",
                        "value": 1
                   }
                   ...
              ]

    }

    In this use case we always want to query and filter using the usageCharacteristic however there is no obvious way to do this!

    What do you suggest?



    ------------------------------
    Vance Shipley
    SigScale Global Inc.
    ------------------------------


  • 2.  RE: Query Complex Types: Array

    TM Forum Member
    Posted Feb 01, 2018 05:23
    The latest version of TMF630 (v17.5.0) still doesn't provide any guidance on the problem of querying on characteristic values.

    While it is clear how to specify complex types using dot notation ("objectName.fieldName") it is less clear, and not explicitly mentioned, how to handle arrays which is a common use case.

    Using TMF635 Usage Management as an example if we wanted to query the resources where a particular characteristic has a particular value we might try:

        /usageManagement/v1/usage?usageCharacteristic.name=poolNumber;usageCharacteristic.value=1

    The problem here is that this would technically match any resource with a characteristic of poolNumber and any characteristic with value 1.

    What we need is a syntax which would group name and value such as possibly:

         /usageManagement/v1/usage?usageCharacteristic={name=originatingNumber;value=676123456789}&usageCharacteristic={name=duration;value=20}

    ... where the above would match usage records where the originatingNumber characteristic value was 676123456789 and the duration value was 20.

    Has anyone considered this issue? Any other suggestions on syntax?





    ------------------------------
    Vance Shipley
    SigScale Global Inc.
    ------------------------------



  • 3.  RE: Query Complex Types: Array

    TM Forum Member
    Posted Feb 01, 2018 16:01
    Edited by Vance Shipley Feb 04, 2018 23:10


  • 4.  RE: Query Complex Types: Array

    TM Forum Member
    Posted Feb 19, 2019 05:37
    Hello,

    I'm Currently facing the exact same issue but with the productInventory Management API.
    Filtering by characteristic is a must, but there is no guideline on how to standardize the way how to create query on arrays to make it assotiave to 1 instance.

    Can you provide the end option you ended up with.

    ------------------------------
    Alexandre Coelho

    ------------------------------



  • 5.  RE: Query Complex Types: Array

    TM Forum Member
    Posted Feb 20, 2019 07:04
    Alexandre,

    I eventually discovered Jira issue AP-832:  Advanced Attribute Filtering Pattern for REST APIs

    This proposal includes an attachment which documents an extended syntax which allows a query of this form:

    ?filter="[{characteristic.contains=[{name=Name,value=Value}]}]"

    At SigScale we implemented parts of this extended syntax, have made extensive use of it, and are quite satisfied with the results. I looked at a number of query patterns but really found this the most satisfactory.

    I will say that I receive a surprising amount of push back from TMF's Chief API Architect whenever I bring it up, so I don't expect to see it endorsed anytime soon. That really doesn't stop server side implementations from supporting this extension however.


    ------------------------------
    Vance Shipley
    SigScale Global Inc.
    ------------------------------



  • 6.  RE: Query Complex Types: Array

    TM Forum Member
    Posted Feb 19, 2019 05:38
    Hello,

    I'm Currently facing the exact same issue but with the productInventory Management API.
    Filtering by characteristic is a must, but there is no guideline on how to standardize the way how to create query on arrays to make it assotiave to 1 instance.

    Can you provide the end option you ended up with.

    ------------------------------
    Alexandre Coelho

    ------------------------------