[User Story] Event ChangeLog

[Lan2u]

Please provide the following information about the user story using the format provided below.

The users role: The Users Meeting Lead / SSC Ents Convener

The users story/action: A user at the users meeting presents conflicting or differing information to that which we currently have and when this is raised the user wishes to know when the previous change was made.

The users reason for taking the action: So that the SSC Ents convener can determine at what users meeting / date the change was made to the event so that they can inform the user.

The expected outcome: Each event has a changelog detailing changes with timestamps and who made the change

[Vitineth]

As per ents-crew/uems-frontend-themis#7, proposing a change to the API

Changed API: GET /events/{id} Old response

get:
      summary: Retrieves a single event
      operationId: get-events-id
      responses:
        '200':
          description: The properties of the event that is specified by the ID given
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SuccessfulAPIResponse'
                  - type: object
                    properties:
                      result:
                        $ref: '#/components/schemas/EventResponse'

To

    get:
      summary: Retrieves a single event
      operationId: get-events-id
      responses:
        '200':
          description: The properties of the event that is specified by the ID given
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SuccessfulAPIResponse'
                  - type: object
                    properties:
                      result:
                        type: object
                        properties:
                          event:
                            $ref: '#/components/schemas/EventResponse'
                          changelog:
                            type: array
                            items:
                              $ref: '#/components/schemas/ActionResponse'

With added schema:

    ActionResponse:
      title: ActionResponse
      type: object
      properties:
        id:
          type: string
          description: The ID of the change
        occurred:
          description: The unix timestamp at which the change occurred
          type: number
        change:
          type: string
          description: A description of the change that took place in JSON format. Change must be versioned for parsing reasons. Schema to be confirmed and documented in future
        user:
          $ref: '#/components/schemas/User'
      required:
        - id
        - occurred
        - change

Overall diff

353a354,381
>     ActionResponse:
>       title: ActionResponse
>       type: object
>       x-examples:
>         example-1:
>           id: 8d8abd3a-da02-4e58-97e8-d3251127c9bf
>           occurred: 0
>           change: '{"version": 0, "change": "status", "prev": "7d4a49cb-c5ac-4cf9-87ed-d17d6cfb0501", "new": "dd48832e-ebd7-4a73-9775-29ee51ca4b14"}'
>           user:
>             id: 48eb7ea4-498a-45cc-bea2-e427925ded50
>             username: admin
>             name: Admin
>       properties:
>         id:
>           type: string
>           description: The ID of the change
>         occurred:
>           description: The unix timestamp at which the change occurred
>           type: number
>         change:
>           type: string
>           description: A description of the change that took place in JSON format. Change must be versioned for parsing reasons. Schema to be confirmed and documented in future
>         user:
>           $ref: '#/components/schemas/User'
>       required:
>         - id
>         - occurred
>         - change
507c544,556
<                         $ref: '#/components/schemas/EventResponse'
---
>                         type: object
>                         properties:
>                           event:
>                             $ref: '#/components/schemas/EventResponse'
>                           changelog:
>                             type: array
>                             items:
>                               $ref: '#/components/schemas/ActionResponse'
>           headers:
>             Links:
>               schema:
>                 type: string
>               description: A set of links pointing to associated resources as per rfc8288
514c563
<       description: Fetches details of a singular event
---
>       description: Fetches details of a singular event including the changelog

Thoughts @Lan2u - not sure if this makes sense commented like this but hopefully you get what I mean. I can open a proper PR with this but I thought I'd get your initial views of this API change before continuing

[Lan2u]

Why ActionResponse as a name? It might make more sense to use a name which more clearly reflects that this is a timestamped change event

[Lan2u]

For the changes why not have the format:

{ field_name: [old_value, new_value] }

[Vitineth]

Why ActionResponse as a name? It might make more sense to use a name which more clearly reflects that this is a timestamped change event

I chose it as it represents an action that was taken on an event. The Response bit is to fit the naming theme of the currently scheme elements defined

[Lan2u]

Why ActionResponse as a name? It might make more sense to use a name which more clearly reflects that this is a timestamped change event

I chose it as it represents an action that was taken on an event. The Response bit is to fit the naming theme of the currently scheme elements defined

I don't see how it's a Response?

[Vitineth]

It's a response from the server. In the API the schemas are generally divided up into ElementCreation, ElementUpdate, ElementResponse because fields are optional or required differently depending on whether the data is for creating something, updating something or a response (ie only responses contain IDs)

[Lan2u]

It's a response from the server. In the API the schemas are generally divided up into ElementCreation, ElementUpdate, ElementResponse because fields are optional or required differently depending on whether the data is for creating something, updating something or a response (ie only responses contain IDs)

But the ActionResponse isn't itself a response it is an object/structure within an already existing response.

Also I think Action is too generic then as if we continue the naming into the backend we will have a type called 'Action' which is not descriptive enough.

[Vitineth]

Could have something like PropertyChange?

[Lan2u]

Could have something like PropertyChange?

Yeah I like this more, might be worth specifying it as EventPropertyChange so as to distinguish this from a VenuePropertyChange or similar

[Vitineth]

But the ActionResponse isn't itself a response it is an object/structure within an already existing response.

True but this naming convention only exists for the types in the API schema. The names shouldn't map on to the backend in any way or anything like that. It's because in the openapi description, these schemas are only to be used as part of responses. It was the most descriptive name I could think of as it only needs to be part of the description online.

[Lan2u]

But the ActionResponse isn't itself a response it is an object/structure within an already existing response.

True but this naming convention only exists for the types in the API schema. The names shouldn't map on to the backend in any way or anything like that. It's because in the openapi description, these schemas are only to be used as part of responses. It was the most descriptive name I could think of as it only needs to be part of the description online.

Yeah but if we don't map names through then the code becomes harder to comprehend for someone who is new and is starting at the documentation and then looks at source code.

[Vitineth]

If you can think of a better name for it we can adjust it, in the context of the API it makes more sense because they are only to be used as responses but I get your point. Could be ResponseComponent or something like that because it will only ever be a component of a response but idk

[Lan2u]

If you can think of a better name for it we can adjust it, in the context of the API it makes more sense because they are only to be used as responses but I get your point. Could be ResponseComponent or something like that because it will only ever be a component of a response but idk

I say we leave it as EventPropertyChangeResponse or just EventPropertyChange and then we can come back to the 'response' bit as that is local to this part of the system.

[Vitineth]

Will add these changes to the open PR for the API and will start working on the frontend assuming this response format

[Lan2u]

Will add these changes to the open PR for the API and will start working on the frontend assuming this response format

Awesome