Open APIs

 View Only
  • 1.  TMF630 and query parameters

    TM Forum Member
    Posted Aug 13, 2021 18:13
    The TMF 630 design guidelines shows examples of the ways to specify single or multiple filter criteria on a query, however I'm looking for some further clarification.

    Per the OpenAPI specification, each field that can be used as a filter can be defined on the operation as a separate query parameter. This provides a self-documenting operation where there is no ambiguity in the query parameters that are supported and makes things straightforward for the server. On the downside, it results in churn of the swagger as query parameters are added or removed.

    Example: GET /api/troubleTicket/?status=acknowledged & creationDate=2017-04-20  
    where both status and creationDate would be described in the Open API spec as query parameters.

    There is an alternative, where a single query parameter is defined that accepts a string which in turn can be made of any name/value pair or complex chaining of criteria. This method puts more work on the server to parse the input but the backend can update the supported parameters without the need to churn the swagger.

    Example:
    Example: GET /api/troubleTicket/query:status=acknowledged & creationDate=2017-04-20 (some delimiter between query and the actual criteria)
    where query is the only query parameter defined in the specification.

    The TMF specifications that I've looked at don't provide the second option and I was wondering if this was an omission or if it's a recommendation for handling query params.
    Does anyone have feedback on the approaches?

    thanks

    ------------------------------
    Lynn Dueck
    Oracle Corporation
    ------------------------------


  • 2.  RE: TMF630 and query parameters

    TM Forum Member
    Posted Aug 15, 2021 14:35
    Hi Lynn
    My feeling is that the the query parameter filter is intended primarily for the new feature of JSON Path filtering, as described in design guidelines part 6.
    In any case, the TMF published swagger files do not include the specific query parameters as part of the GET (list) operation specification. The contract in this area is implicit.

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



  • 3.  RE: TMF630 and query parameters

    Posted Aug 16, 2021 01:32
    Edited by Hanumantha Marikanti Aug 17, 2021 04:46
    Hi,

    Just a thought as a API designer  & developer. 
    Any change or enhancement we make to the API should be somewhere documented to publish to the consumers etc.
    I think Swagger is the best place to update such changes. The second approach bypasses this practice, we may end up having broken document/contract over a period of time. 

    Thanks.
    Hanumantha Marikanti
    Open API enthusiast

    ------------------------------
    Hanumantha Marikanti
    Saralam Technologies
    ------------------------------



  • 4.  RE: TMF630 and query parameters

    TM Forum Member
    Posted May 31, 2023 09:03
    Edited by Lynn Dueck Jun 01, 2023 11:59

    Hi @Jonathan Goldberg ,
    I'm returning to this thread for further clarification - I hope you can help.

    If the 630 guidelines dictate that all first level attributes must be supported as query parameters, why do the swagger files not align with that? If an application natively understands the openAPI/swagger, then by omitting the list of attributes as query parameters from the specification, it means that the application cannot support the use case. Which of course then goes against 630 guidelines.

    Is that a bug or is there some other reason that the swagger does not accurately reflect the expectations from a 630 perspective?

    thanks for your help,



    ------------------------------
    Lynn Dueck
    Oracle Corporation
    ------------------------------



  • 5.  RE: TMF630 and query parameters

    TM Forum Member
    Posted Jun 07, 2023 12:22

    Hi Lynn

    It's a good point

    This is a question for the guidelines maestro @Florin Tene and the tooling maestro @Joel Burgess .



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



  • 6.  RE: TMF630 and query parameters

    TM Forum Member
    Posted Jun 07, 2023 14:40

    Thanks @Jonathan Goldberg . Lynn, as you stated, there is no straightforward way for an OAS to support unnamed query parameters.

    While it is certainly possible to integrate all top-tier resource parameters into the OAS, it might result in an unwieldy and overly complex structure. Additionally, incorporating operators (like .gt, .gte) and implementing sub-resource renders this approach unmanageable. This strategy risks creating a conflict between TMF630 and OAS, which could complicate things further.

    As an alternative, I propose the use of JSON path, which is significantly more expressive and adaptive.

    In terms of accommodating the query parameter filter patterns, one viable strategy could be to introduce a singular query parameter that encapsulates all the specific query parameters that need to be filtered, but at this point it is probably just easier to adopt JSON path.

    My primary aim is to establish a machine-readable enforceable OAS, but there's a question of whether TMF630 could override the OAS for this particular function. It's likely that any proposed change would necessitate an amendment to the TMF630.

    There is an existing pull request that introduces the filter query parameter. However, it appears that it has yet to receive approval. 

     This is an area we may need to look into further. @Florin Tene, thoughts?



    ------------------------------
    Joel Burgess
    Oracle Corporation
    ------------------------------



  • 7.  RE: TMF630 and query parameters

    TM Forum Member
    Posted Jun 08, 2023 10:56

    Thank you @Jonathan Goldberg  & @Joel Burgess  - I agree with your comments; adding all attributes in the OAS will result in an unmanageable specification.

    The TMF630 does provide support & guidance for the implementations across all the TMForum APIs Catalogue on rules, patterns, usage, etc.

    Regarding the comment about adding only all the top-tier attributes in the OAS, that will create more issues than it solves, not to mention the complexity of the OAS.

    A particular TMF API implementation might decide that it won't support the full definition of a specific resource schema. In this case, adding all the top-tier attributes in the OAS will create expectations from consumers that the backend implementations can't support.

    The coverage of the statement from the TMF630, "Attribute selection MUST be enabled on all first-level attributes but not on inner classes", is to remain valid in all implementations. For example, if the implementation reduces the resource schema and now includes only two top-level classes, having all the top-level attributes from the original definition of the resource listed causes more problems. So the above TMF630 statement remains true whether all the resource schema is being used or if it was reduced to backend capabilities.

    @Jonathan Goldberg  & @Joel Burgess correctly point out that the JSON Path support (TMF630 - Part 6) was explicitly added to provide a standard mechanism for complex queries.  

    TMF630 - Part 6 details the behaviour of the selector called "filter", which allows you to pass complex query parameters, similar to the suggestion from the first comment ("query"). To highlight, JSONPath does support natively the . (dot) notation. 

    As highlighted in the TMF630 (4.4.1), the collection query based on attributes and the . (dot) notation provides a simple filtering mechanism, and the recommendation is that JSONPath should be used instead as it does provide a generic behaviour and it does not require listing of any level attributes in the query.  

    Regarding the earlier comment, "broken document/contract over time", in my view, all the APIs should be governed within an organisation, whether CSP or product supplier. As part of the governance piece (which is now, by default, offered by the majority of the API Gateways out there), the contracts should be versioned and exposed accordingly to the current capabilities supported by the backend implementations. In summary, any change to the OAS contract exposed by an API Gateway must be versioned, checked for compliance, validated & tested against the backend before publication to the company's internal or external consumers. The API Gateways out there, offer plenty of tools for the governance and management of the APIs lifecycle within the enterprise.

    Thank you,

    Florin

      



    ------------------------------
    Florin Tene
    CityFibre
    ------------------------------