Page MenuHomePhabricator

Create the documentation of the API - List of created event registrations
Open, Needs TriagePublic1 Estimated Story Points

Description

As a Dev I want to create the documentation of the API - List of created event registrations

Acceptance Criteria:

-The Documentation of the API should have at least:

  • Description
  • Method (GET, POST, etc..)
  • Payload (json)
  • Success Response (json)
  • Error Response (json)

Event Timeline

"Review": docs should be updated to reflect the merged version.

@Daimona @cmelo

at https://www.mediawiki.org/wiki/Extension:CampaignEvents/Api
-> look at List all registrations from an Organizer
-> in the json payload, for the key of event_id the value listed is Name of the event - It should be Id of the event, or something along those lines. I can make this change in the doc, just give me a thumbs up if Id of the event is how you would like it listed.

[
	{ 
		"event_id": "<Name of the event>",
		"event_name": "<Name of the event>",
	}
]

@Daimona @cmelo

at https://www.mediawiki.org/wiki/Extension:CampaignEvents/Api
-> look at List all registrations from an Organizer
-> in the json payload, for the key of event_id the value listed is Name of the event - It should be Id of the event, or something along those lines. I can make this change in the doc, just give me a thumbs up if Id of the event is how you would like it listed.

[
	{ 
		"event_id": "<Name of the event>",
		"event_name": "<Name of the event>",
	}
]

Sounds good to me!

another one for @Daimona @cmelo or @ifried (i believe this is in scope for this ticket)

at https://www.mediawiki.org/wiki/Extension:CampaignEvents/Api

--> look at Get details of a registration

--> in the 404 error message, the documentation reads:

The given ID does not correspond to an existing event registration

but when hitting the endpoint campaignevents/v0/event_registration/{id} with an invalid ID, the error message is:

No event exists with the given ID

To keep those consistent, should I change the documentation or should the response be changed in the code base? I'm not sure which is the correct one to use.


also of note, when passing a non-integer parameter into the query string for this request, it brings back a 400 Bad Request, parameter-validation-failed with error message Invalid value "{value}" for integer parameter "id", which is not yet documented in the API doc for this endpoint. Should that error message be in the doc as well, or is this a more generic systemwide error message when an invalid type is passed as a param?

another one for @Daimona @cmelo or @ifried (i believe this is in scope for this ticket)

at https://www.mediawiki.org/wiki/Extension:CampaignEvents/Api

--> look at Get details of a registration

--> in the 404 error message, the documentation reads:

The given ID does not correspond to an existing event registration

but when hitting the endpoint campaignevents/v0/event_registration/{id} with an invalid ID, the error message is:

No event exists with the given ID

To keep those consistent, should I change the documentation or should the response be changed in the code base? I'm not sure which is the correct one to use.

IMO it's not necessary to use the same wording in the code and in the docs, because they could easily go out of sync. Happy to hear what the others think, though.

also of note, when passing a non-integer parameter into the query string for this request, it brings back a 400 Bad Request, parameter-validation-failed with error message Invalid value "{value}" for integer parameter "id", which is not yet documented in the API doc for this endpoint. Should that error message be in the doc as well, or is this a more generic systemwide error message when an invalid type is passed as a param?

These are more generic errors emitted by the core param validation logic. I don't think it's necessary to document them, as long as we document the type of each parameter.

another one for @Daimona @cmelo or @ifried (i believe this is in scope for this ticket)

at https://www.mediawiki.org/wiki/Extension:CampaignEvents/Api

--> look at Get details of a registration

--> in the 404 error message, the documentation reads:

The given ID does not correspond to an existing event registration

but when hitting the endpoint campaignevents/v0/event_registration/{id} with an invalid ID, the error message is:

No event exists with the given ID

To keep those consistent, should I change the documentation or should the response be changed in the code base? I'm not sure which is the correct one to use.

IMO it's not necessary to use the same wording in the code and in the docs, because they could easily go out of sync. Happy to hear what the others think, though.

also of note, when passing a non-integer parameter into the query string for this request, it brings back a 400 Bad Request, parameter-validation-failed with error message Invalid value "{value}" for integer parameter "id", which is not yet documented in the API doc for this endpoint. Should that error message be in the doc as well, or is this a more generic systemwide error message when an invalid type is passed as a param?

These are more generic errors emitted by the core param validation logic. I don't think it's necessary to document them, as long as we document the type of each parameter.

Okay thanks I'll mark this as complete then