Open APIs

  • 1.  TMF629 How are Filtered Search params described in swagger.json

    TM Forum Member
    Posted Oct 29, 2021 07:18
    Edited by Eduardo Sanchez Oct 29, 2021 07:20
    I'm working on the implementation of the TMF 629 Customer API and I am struggling to understand how should the code generator use the official swagger.json file.

    Currently based on that swagger.json the two methods that implement Filtered Search (listCustomer and retrieveCustomer) include only the parameters described in the swagger.json, this code is autogenerated from the OpenAPI code generator:

    listCustomer(String fields, Integer offset, Integer limit) - defined in swagger.json as:
      "paths" : {
        "/customer" : {
          "get" : {
            "tags" : [ "customer" ],
            "summary" : "List or find Customer objects",
            "description" : "This operation list or find Customer entities",
            "operationId" : "listCustomer",
            "parameters" : [ {
              "name" : "fields",
              "in" : "query",
              "description" : "Comma-separated properties to be provided in response",
              "required" : false,
              "type" : "string"
            }, {
              "name" : "offset",
              "in" : "query",
              "description" : "Requested index for start of resources to be provided in response",
              "required" : false,
              "type" : "integer"
            }, {
              "name" : "limit",
              "in" : "query",
              "description" : "Requested number of resources to be provided in response",
              "required" : false,
              "type" : "integer"
            } ],​


    retrieveCustomer(String id, String fields) - defined in swagger.json as:
        "/customer/{id}" : {
          "get" : {
            "tags" : [ "customer" ],
            "summary" : "Retrieves a Customer by ID",
            "description" : "This operation retrieves a Customer entity. Attribute selection is enabled for all first level attributes.",
            "operationId" : "retrieveCustomer",
            "parameters" : [ {
              "name" : "id",
              "in" : "path",
              "description" : "Identifier of the Customer",
              "required" : true,
              "type" : "string"
            }, {
              "name" : "fields",
              "in" : "query",
              "description" : "Comma-separated properties to provide in response",
              "required" : false,
              "type" : "string"
            } ],​

    The code generator uses the swagger.json to create the methods signature, and their signatures seem correct.

    The documentation (and the conformance tests CTK) request the implementation of the Filtered Search functionality so that any field of the customer can be used to search for a specific customer, ex:
    {{Customer}}customer?name=mike <-- Searches for customers with 'name' field equals to 'mike'.

    Documented as:
    "Filtered Search: : A filtered search can be applied using query parameters in order to obtain only the resource entities that meet the criteria defined by the filtering parameters included in the query request. Several elements can be applied to the filtered search. In that case logic, a logical AND is applied to combine the criteria (e.g.:?category=<value> &state=<value>)"

    In the documentation is not clear if this Filtered Search is mandatory or optional (I assume is mandatory since is part of the CTK):
    "Filtering may be available depending on the compliance level supported by an implementation"

    Could somebody clarify if the Filtered Search is mandatory? In case of being mandatory it would be useful to know how can this be implemented using the swagger.json and the code generator.

    Thanks for the help!

    ------------------------------
    Eduardo Sanchez
    MATRIXX Software
    ------------------------------


  • 2.  RE: TMF629 How are Filtered Search params described in swagger.json

    TM Forum Member
    Posted Oct 29, 2021 11:01
    Hi,

    The use of query and fields to search and filter is not defined in the swagger.
    The description of that syntax can be found in TMF630 Part 1.

    Two approaches are possible for this:
    • Classic: The search and filter capabilities are defined by the business application that is behind the API
    • CQRS(Command Query Responsability Separation): This approach assumes the applications faithfully implement all the Notifications defined in the API with full payload. The API GET queries then use the EventLog to get the latest representation of each object and implements the Searching and Filtering in the API layer without ever calling the application. In the background the API layer could build a cache with JSON payloads in a text database for high performance reponses and supporting the full reach of the TMF630 specification.
    My company offers a product that implements the second approach.

    ------------------------------
    Koen Peeters
    Ciminko Luxembourg
    ------------------------------



  • 3.  RE: TMF629 How are Filtered Search params described in swagger.json

    TM Forum Member
    Posted Oct 31, 2021 06:05
    Adding to Koen's note:
    In V4 for the guidelines TMF630, a new optional paradigm was introduced, JSON Path. Take a look at Part 6 in the guidelines (download here).
    The exact search parameters are deliberately not part of the swagger, and you can understand, especially with the JSON Path representation, that would not have been practical.
    The conformance profile of each API should define (in the GET section) which searches are supported.

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