Changes for portal/static/docs/api/v0/openapi-spec.yaml: 6 added lines, 1 removed line.
Original line number
Diff line number
Diff line
@@ -43,7 +43,12 @@ paths:
`/agendas/-/items` seems needlessly complicated, but there is a reason for that:
<!-- TODO -->
In REST, it is common to specify paths of the form `/{type}/<id>`. If `{type}` is a composite, i.e., consists of instances of a `{subtype}`, REST recommends a path of the form `/{type}/<id>/{subtype}/<id>` to address a particular instance of the subtype. For endpoints that return all instances of a particular type, `/{type}` is used. In case of composite instances, `/{type}/<id>/{subtype}` is used.
It felt wrong just to use `/items` to get all agenda items, as items is very unspecific. `/agenda-items` would have been possible, but a bit ugly. We therefore opted to model items as composites of an agenda, leaving us with `/agendas/<id>/items` as path to get all items.
However, we currently don't model multiple agendas (and maybe never will). To still keep the pattern, we therefore used an id of `-` to signify something like “_the one_ agenda, like, you know what we're talking about”. Should we ever introduce several agendas, distinguished
by ids, we could in a compatible way adjust the API to also allow actual ids in the path.
/version:
summary:Path used to get details about the version of this application.
