Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Attribute startsAt should be non-mandatory #262

Closed
ilya-smirnov-berlin opened this issue Jul 31, 2024 · 2 comments · Fixed by #267
Closed

Attribute startsAt should be non-mandatory #262

ilya-smirnov-berlin opened this issue Jul 31, 2024 · 2 comments · Fixed by #267
Labels
correction correction in documentation

Comments

@ilya-smirnov-berlin
Copy link

Problem description

Currently the attribute startsAt in Event Notification Template is mandatory. When the subscription is used in asynchronous mode and not started yet (status ACTIVATION_REQUESTED, or SUBSCRIPTION_UNPROCESSABLE as suggested in #243) the starting time is not known.
Also the name of the attribute implies a future date-time which is not the case since this timestamp is set to creation time of subscription and is always in the past (compare to QoD API specification: https://github.com/camaraproject/QualityOnDemand/blob/d6a3f239622e7a840ac049dfa8b2c74a3aea87b0/code/API_definitions/quality-on-demand.yaml#L533 ).
According to this fact maybe the description of this attribute can be changed to the past form.

Expected behavior

  • startsAt should be optional
  • Renaming from startsAt to startedAt
  • Description of this attribute should contain only past form verb:
    instead of
    Date when the event subscription will begin/began
    I suggest
    Date and time when the event subscription has started
@ilya-smirnov-berlin ilya-smirnov-berlin added the correction correction in documentation label Jul 31, 2024
@rartych
Copy link
Collaborator

rartych commented Jul 31, 2024

* startsAt should be optional

It is optional in API Design Guidelines, so it should be corrected in template file .

* Renaming from startsAt to startedAt
* Description of this attribute should contain only past form verb:
  instead of
  _Date when the event subscription will begin/began_
  I suggest
  _Date and time when the event subscription has started_

The Subscription component is currently used in the response only (I think initially it was also placed in the subscription request), the question is whether we should change parameter name within this release, that would impose implementing this change in other subscription APIs (in short time before metarelease ).

@PedroDiez
Copy link
Collaborator

Understood the rationale and it makes sense to have it optional.

Regarding the name, I suggest to keep it and not change in anycase as in the description the context will be provided.
We also use "expiresAt" for a future Date.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
correction correction in documentation
Projects
None yet
3 participants