Open APIs

 View Only
  • 1.  TMF688 Event Model vs CloudEvents vs rfc9457

    TM Forum Member
    Posted Nov 03, 2023 09:46

    Struggling a bit with having too many choices for formats for events/responses. My goal is to publish events to Kafka as a result of service order (TMF641) processing. I want to offer synchronous responses to a POST that conform to rfc9457 Problem Detail in cases where there are issues. I also need to submit events to Kafka that would also include problem details.  Giving the use of Kafka, we want to also adhere to the CloudEvent model. I have started with a CloudEvent that incorporates rfc9457, but now am wondering if I should simply replace the CloudEvent with the TMF688 model and incorporate rfc9457 into that. 

    :-) Thoughts?



    ------------------------------
    Jay Hamilton

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


  • 2.  RE: TMF688 Event Model vs CloudEvents vs rfc9457

    TM Forum Member
    Posted Nov 09, 2023 01:54

    Hi Jay

    Perhaps there is a confusion here between modeling of an event and of a problem?

    TMF688 gives an abstraction of an event model, where the event schema includes generic data relevant to all events, together with a payload that is strongly-typed and defined within each owning API. Typically it's the entity itself, so that (for example) a CustomerCreated event will have a payload of type Customer (as defined in TMF629 Customer Management API).

    For problems, the TMF Open API tooling generates a predefined Error schema as the body for each of the error response statuses (4xx and 5xx) in the swagger/OAS for each API. The error schema looks like this (below). It can probably be mapped to the corresponding properties in rfc9457, but to actually adopt the rfc would be a big backward compatibility break in all the API contracts.

    Hope it helps. 

        Error:
          discriminator:
            propertyName: '@type'
            mapping:
              Error: '#/components/schemas/Error'
          allOf:
            - $ref: '#/components/schemas/Extensible'
            - type: object
              required:
                - code
                - reason
              properties:
                code:
                  type: string
                  description: 'Application relevant detail, defined in the API or a common list.'
                reason:
                  type: string
                  description: Explanation of the reason for the error which can be shown to a client user.
                message:
                  type: string
                  description: >-
                    More details and corrective actions related to the error which can be shown to a
                    client user.
                status:
                  type: string
                  description: HTTP Error code extension
                referenceError:
                  type: string
                  description: URI of documentation describing the error.
          description: 'Used when an API throws an Error, typically with a HTTP error response-code (3xx, 4xx, 5xx)'
    


    ------------------------------
    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: TMF688 Event Model vs CloudEvents vs rfc9457

    TM Forum Member
    Posted Nov 10, 2023 10:16
    Edited by Jay Hamilton Nov 10, 2023 10:17

    Thanks for the response, Jonathan. Good point regarding the distinction between event and problem. I have elected to blur that line a bit but will reconsider. That said, my larger issue is what I perceive to be two approaches, CloudEvent (https://cloudevents.io/) and TMF688, that attempts to achieve the same goal. 



    ------------------------------
    Jay Hamilton

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



  • 4.  RE: TMF688 Event Model vs CloudEvents vs rfc9457

    TM Forum Member
    Posted Nov 12, 2023 03:14

    Thanks for bringing this to our attention. I personally was not aware of this CloudEvents initiative - I'll pass it on to the relevant people in the Open API project.



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