Open Lan2u opened 4 years ago
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
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
For the changes why not have the format:
{ field_name: [old_value, new_value] }
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
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?
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)
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.
Could have something like PropertyChange
?
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
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.
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.
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
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.
Will add these changes to the open PR for the API and will start working on the frontend assuming this response format
Will add these changes to the open PR for the API and will start working on the frontend assuming this response format
Awesome
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