(vitineth/patch/api) Updating openapi specification

[Vitineth]

This now handles almost all endpoints that I can think of but will likely need some more revisions

Updated readable spec is now available here:

• Stoplight (preferred): https://xiomi.stoplight.io/docs/uems-gateway-api/reference/kill-me.yaml
  • ignore the url.. had some trouble making it
• Swagger: https://app.swaggerhub.com/apis-docs/ents-crew/uems-gatway/0.0.1-alpha
  • its raising weird errors when saving so prefer the other one but I think it's up to date

[Lan2u]

In this what is an 'ent'?

[Vitineth]

In this what is an 'ent'?

Short way to write "ents-state" so ents can have their own status on an event, distinct from a building status

[Lan2u]

In this what is an 'ent'?

Short way to write "ents-state" so ents can have their own status on an event, distinct from a building status

So as in its a flag set by the convener (or whoever) to indicate the stage that the event has been processed to?

[Vitineth]

In this what is an 'ent'?

Short way to write "ents-state" so ents can have their own status on an event, distinct from a building status

So as in its a flag set by the convener (or whoever) to indicate the stage that the event has been processed to?

Yeah, something like "awaiting users", "waiting on requirements" or "awaiting techs"

Could do with a better name but wasn't sure what

[Lan2u]

In this what is an 'ent'?

Short way to write "ents-state" so ents can have their own status on an event, distinct from a building status

So as in its a flag set by the convener (or whoever) to indicate the stage that the event has been processed to?

Yeah, something like "awaiting users", "waiting on requirements" or "awaiting techs"

Could do with a better name but wasn't sure what

I think implementing the system for adding/removing/getting these status names is a low priority as we can get very far simply by using a fixed list of allowed statuses when updating an event

Yeah that sounds good, as long as we have the get endpoints that's fine

[Lan2u]

In this what is an 'ent'?

Short way to write "ents-state" so ents can have their own status on an event, distinct from a building status

So as in its a flag set by the convener (or whoever) to indicate the stage that the event has been processed to?

Yeah, something like "awaiting users", "waiting on requirements" or "awaiting techs" Could do with a better name but wasn't sure what

I think implementing the system for adding/removing/getting these status names is a low priority as we can get very far simply by using a fixed list of allowed statuses when updating an event.

In line with this I think this API is a good starting point, it will be much easier to handle implementing if we take each part and split it into a separate issue to work on. I suspect there might be some stuff that is missed/doesn't work in practice so we will need to keep evaluating this as we go.

[Vitineth]

I think implementing the system for adding/removing/getting these status names is a low priority as we can get very far simply by using a fixed list of allowed statuses when updating an event.

In line with this I think this API is a good starting point, it will be much easier to handle implementing if we take each part and split it into a separate issue to work on. I suspect there might be some stuff that is missed/doesn't work in practice so we will need to keep evaluating this as we go.

Sounds good, basically get endpoints are the most important right now front-end wise and then can work up from there

[Lan2u]

I think implementing the system for adding/removing/getting these status names is a low priority as we can get very far simply by using a fixed list of allowed statuses when updating an event.

In line with this I think this API is a good starting point, it will be much easier to handle implementing if we take each part and split it into a separate issue to work on. I suspect there might be some stuff that is missed/doesn't work in practice so we will need to keep evaluating this as we go.

Sounds good, basically get endpoints are the most important right now front-end wise and then can work up from there

Awesome - I'll approve this PR and the first thing we need to do is make some issues representing chunks of this

[Vitineth]

Not to be addressed in this version but V2 of the API should using pagination (https://docs.microsoft.com/en-us/azure/architecture/best-practices/api-design#filter-and-paginate-data)

[Lan2u]

Not to be addressed in this version but V2 of the API should using pagination (https://docs.microsoft.com/en-us/azure/architecture/best-practices/api-design#filter-and-paginate-data)

Very much agree, I considered putting a limit on before but decided to leave it for now until we have a more firm understanding of how the system will actually behave

[Vitineth]

Not to be addressed in this version but V2 of the API should using pagination (https://docs.microsoft.com/en-us/azure/architecture/best-practices/api-design#filter-and-paginate-data)

Very much agree, I considered putting a limit on before but decided to leave it for now until we have a more firm understanding of how the system will actually behave

Fair enough, I figured we won't have enough data to make it worth it for a while so there is time to get a working platform then migrate to one with pagination

[Lan2u]

Not to be addressed in this version but V2 of the API should using pagination (https://docs.microsoft.com/en-us/azure/architecture/best-practices/api-design#filter-and-paginate-data)

Very much agree, I considered putting a limit on before but decided to leave it for now until we have a more firm understanding of how the system will actually behave

Fair enough, I figured we won't have enough data to make it worth it for a while so there is time to get a working platform then migrate to one with pagination

Probably a good idea to put the parameters into the requests but leave them unused for now.

Also we might do well to include versioning in the API once we have a stable version.

[Vitineth]

I'm currently reading best practices so will have a couple comments as I find them. Should support each endpoint returning links to related endpoints as per the Microsoft recommendations. This can be added via the proposed link headers (https://tools.ietf.org/html/rfc8288) or through a more standard JSON response. This can be decided later because it's not a priority

[Vitineth]

Not to be addressed in this version but V2 of the API should using pagination (https://docs.microsoft.com/en-us/azure/architecture/best-practices/api-design#filter-and-paginate-data)

Very much agree, I considered putting a limit on before but decided to leave it for now until we have a more firm understanding of how the system will actually behave

Fair enough, I figured we won't have enough data to make it worth it for a while so there is time to get a working platform then migrate to one with pagination

Probably a good idea to put the parameters into the requests but leave them unused for now.

Also we might do well to include versioning in the API once we have a stable version.

Good idea, the openapi spec currently lists the base API endpoint as /api/v0 to allow for versioning in the future

[Lan2u]

With regards to the file handling (e.g. /events/{id}/files/{file}) what does {file} refer to? is it the raw file-name, a human-readable name or a hybrid?

This would revolve around how we want to represent file objects to the front-end.

• Using the raw file names is potentially quite messy and hard to use (especially if we have a complex file storage hierarchy)
• Using human readable names is much better but we will need to decide if those names must be always unique or only unique to the event. For example we might have a lx-plot.pdf for 2 different events and even though the name is the same the file may or may not be different.
• We could also just use file ID's for everything as an abstraction over the actual file-path (and then map the ID -> the file at the back-end)

[Lan2u]

Also, all API endpoints from now on should return 501 Not Implemented if they aren't implemented so we can distinguish between intentional 404 and not-implemented 404.

[Vitineth]

With regards to the file handling (e.g. /events/{id}/files/{file}) what does {file} refer to? is it the raw file-name, a human-readable name or a hybrid?

This would revolve around how we want to represent file objects to the front-end.

• Using the raw file names is potentially quite messy and hard to use (especially if we have a complex file storage hierarchy)
• Using human readable names is much better but we will need to decide if those names must be always unique or only unique to the event. For example we might have a lx-plot.pdf for 2 different events and even though the name is the same the file may or may not be different.
• We could also just use file ID's for everything as an abstraction over the actual file-path (and then map the ID -> the file at the back-end)

I was imagining a file ID but could also use a slug version of the filename (https://www.npmjs.com/package/slug) but considering this endpoint is only for metadata (except for uploading) it doesn't really matter

[Vitineth]

Re-requesting review for changes to DELETE and POST responses