Open APIs

 View Only
  • 1.  REST API guidelines - Filtering

    Posted Nov 20, 2018 04:39

    After reading the REST design guidelines 3.0 R17.5.1, specifically the filtering part, with the objective of understanding how can I filter while using AND and OR logic, I was unable to understand how this is done, following the guidelines.
    In section "Query Resources with attribute filtering" two examples of ANDED and ORING behavior are displayed. According to the text right above these examples, in order to use ORING one can repeat the same attribute name multiple times while having different values. One can also specify one attribute name and use both "," or ";" to split the multiple attribute values.
    If we look closely to the ANDED and ORING examples provided in the REST design guidelines:
    • Using ANDED to describe "017-04-20 >dateTime>2013-04-20" :GET /troubleTicket?dateTime%3E2013-04-20&dateTime%3C2017-04-20
    • Using ORING to describe dateTime<2013-04-20 or dateTime<2017-04-20 :GET /troubleTicket?dateTime%3C2013-04-20;dateTime%3E2017-04-20

    The query used to express an ANDED behavior follows the same rules of the ORING, where we can have the same attribute name repeated multiple times with different attribute values. Or am I missing something while interpreting these examples?
    Or when in the document is stated that the attribute name can be repeated, it actually means attribute name plus the operator, and only in that case we are dealing with a ORING behavior. When we have duplicated attribute names but different operators this is considered to be an AND behavior. Is that the case?

    If someone could point me in the right direction, or indicate any documentation that I should read that I might have missed, I would be greatly appreciated.

    Thank you in advance.

    Pedro Sanches

  • 2.  RE: REST API guidelines - Filtering

    Posted Oct 03, 2021 06:29
    Edited by Ebrahim Mirzazadeh Oct 03, 2021 06:53

    I would appreciate if someone please clarify this :

    We have 3 ORING syntax, listed below for attribute value ORING. 
    TMF630v4.2.0 -> Page 30

    1 - [{attributeName}={attributeValue}&*]
    2- [{attributeName}={attributeValue},\{ attributeValue}*]
    3- [{attributeName}={attributeValue};{attributeValue}*]

    TMF630v4.2.0 -> Page 31

    Using ANDED to describe "017-04-20 >dateTime>2013-04-20" :
    • GET /api/troubleTicket?dateTime%3E2013-04-20&dateTime%3C2017-04-20
    Using ORING to describe dateTime<2013-04-20 or dateTime<2017-04-20 :
    • GET /api/troubleTicket?dateTime%3C2013-04-20;dateTime%3C2017-04-20

    Is this a correct sample ? 

    According to syntax #1, first GET must be interpreted as OR where dateTime is repeated separating with & delimiter.

    According to syntaxt #2 and #3 , this ORING is wrong and supposed to be sent as below :

    Syntaxt 3: GET /api/troubleTicket?dateTime%3C2013-04-20;2017-04-20


    ​​Syntax 2: GET /api/troubleTicket?dateTime%3C2013-04-20,2017-04-20

    Thank you

    Ebrahim Mirzazadeh

  • 3.  RE: REST API guidelines - Filtering

    TM Forum Member
    Posted Jul 04, 2022 21:31
    Thanks for providing the 3 ORing syntax options.

    The first option is understandable, but I can't use it in my specific case.

    I could use the second option (,) and the third (;), both using a separator, but they are problematic because the attribute names or values may contain the character in question (, or ;) which would make parsing impossible. These options must necessarily include a way to escape the separators. URL encoding (%2C and %3B) would not work because web servers would decode those back to , and % respectively before sending them to be processed by my code. Of course I could just make up an escape mechanism myself (e.g. \, \\) but it would be better to follow a standard.

    Any suggestions?

    Emmanuel Proulx
    Amdocs Management Limited

  • 4.  RE: REST API guidelines - Filtering

    Posted Jul 11, 2022 03:51
    We ended up using JSONPath in case we need ORing or something more special than just ANDing.
    Also, ANDing is postulated as attibuteName in [array, of, values] when the query string contains several instances of attrubuteName.

    Viktor Aleksandrov
    OJSC "VimpelCom"

  • 5.  RE: REST API guidelines - Filtering

    TM Forum Member
    Posted Jul 12, 2022 01:17
    @Emmanuel Proulx wrote:
    > These options must necessarily include a way to escape the separators.

    You should have a careful read of RFC3896 2.2 Reserved Characters.​ 
    | If data for a URI component would conflict with a reserved character's purpose as a delimiter, then the conflicting data must be percent-encoded before the URI is formed.

    Percent encoding is not applied half hazardly and RFC3896 spells this out.  You may use reserved characters in attribute names, although it's a terrible idea, however you will need to percent-encode them and be sure that you apply your encoding and decoding appropriately.

    Vance Shipley

  • 6.  RE: REST API guidelines - Filtering

    TM Forum Member
    Posted Jul 12, 2022 09:20
    I didn't realize that semicolon (;) is a reserved character for URLs. So that means the URL encoding should work.
    I will give that a try.

    Emmanuel Proulx
    Amdocs Management Limited