Extension:CampaignEvents/Api
This page is currently a draft.
|
This page lists all endpoints available for the CampaignEvents extension. Note that all POST, PUT, and DELETE endpoints can be used either with the OAuth extension authorization process, or with cookie-based authentication. If using cookie-based authentication, the request body should contain a CSRF token, specified as "token": "token-goes-here"
. To get a CSRF token, see the Action API.
Enable an event registration
editRoute | /campaignevents/v0/event_registration
|
---|---|
Content type | application/json
|
Method | POST
|
Returns | JSON object: { "id": "<ID of the registration (integer)>" }
|
Enables an event registration. The performer of the request is also automatically added as event organizer.
Request schema
editevent_page
required | title |
Title of the associated event page. Must be a page on the current wiki. |
chat_url
optional | string |
Invite link for a chat group |
tracking_tool_id
optional | string |
ID of a tracking tool to link to the event. Currently, the only supported tool is the Programs & Events Dashboard, whose ID is wikimedia-pe-dashboard .
|
tracking_tool_event_id
optional | string |
Identifier of this event within the tracking tool specified. For the Programs & Events Dashboard, this corresponds to the course slug (e.g., "Institution/CourseName"). |
timezone
required | string |
Timezone identifier to use with the start and end time, in any format accepted by PHP. |
start_time
required | timestamp |
Timestamp of the event start time, in MW format (e.g., "20220414160000"), local time |
end_time
required | timestamp |
Timestamp of the event start time, in MW format (e.g., "20220414160000"), local time |
online_meeting
optional | boolean |
Whether the event is online |
inperson_meeting
optional | boolean |
Whether the event is in-person |
meeting_url
optional | string |
For online events, the URL of the video call |
meeting_country
optional | string |
For in-person events, the country where the event takes place |
meeting_address
optional | string |
For in-person events, the full address where the event takes place |
Responses
edit201 | Success: the event registration was enabled. The Location header shall point to the registration reource. |
---|---|
400 | The event data is invalid |
403 | The provided CSRF token does not match |
403 | You cannot enable event registrations |
403 | You cannot enable event registration for the given event page |
Edit an event registration
editRoute | /campaignevents/v0/event_registration/{id}
|
---|---|
Content type | application/json
|
Method | PUT
|
Returns | Nothing |
Edits an event registration.
Parameters
editid
required | integer |
ID of the event registration |
Request schema
editevent_page
required | title |
Title of the associated event page. Must be a page on the current wiki. |
status
required | string |
Status of the event ("open", "closed") |
chat_url
optional | string |
Invite link for a chat group |
tracking_tool_id
optional | string |
ID of a tracking tool to link to the event. Currently, the only supported tool is the Programs & Events Dashboard, whose ID is wikimedia-pe-dashboard .
|
tracking_tool_event_id
optional | string |
Identifier of this event within the tracking tool specified. For the Programs & Events Dashboard, this corresponds to the course slug (e.g., "Institution/CourseName"). |
timezone
required | string |
Timezone identifier to use with the start and end time, in any format accepted by PHP. |
start_time
required | timestamp |
Timestamp of the event start time, in MW format (e.g., "20220414160000"), local time |
end_time
required | timestamp |
Timestamp of the event start time, in MW format (e.g., "20220414160000"), local time |
online_meeting
optional | boolean |
Whether the event is online |
inperson_meeting
optional | boolean |
Whether the event is in-person |
meeting_url
optional | string |
For online events, the URL of the video call |
meeting_country
optional | string |
For in-person events, the country where the event takes place |
meeting_address
optional | string |
For in-person events, the full address where the event takes place |
Responses
edit204 | Success: the event registration was edited. |
---|---|
400 | The event data is invalid |
403 | The provided CSRF token does not match |
400 | The event page is not on another wiki, and the registration should be edited from there |
403 | You cannot edit event registrations |
403 | You cannot edit an event registration for the given event page |
404 | The given ID does not correspond to an existing event registration |
List all events from an organizer
editRoute | /campaignevents/v0/organizer/{userid}/event_registrations
|
---|---|
Content type | application/json
|
Method | GET
|
Returns | JSON object with an array of event registrations: [
{
"event_id": "<Id of the event (integer)>",
"event_name": "<Name of the event>",
}
]
If the event is deleted, there's an additional |
Lists all the event registrations from an organizer.
Parameters
edituserid
required | integer |
The central user ID of the organizer |
Responses
edit201 | Success: list all the events. |
---|---|
404 | The user does not exist. |
List all events a participant has registered for
editRoute | /campaignevents/v0/participant/{userid}/event_registrations
|
---|---|
Content type | application/json
|
Method | GET
|
Returns | JSON object with an array of event registrations: [
{
"event_id": "<ID of the event (integer)>",
"event_name": "<Name of the event>",
}
]
If the event is deleted, there's an additional |
Lists all the event registrations a participant has registered for.
Parameters
edituserid
required | integer |
The central user ID of the participant |
Responses
edit201 | Success: list all the events. |
---|---|
404 | The user does not exist. |
Register as a participant
editRoute | /campaignevents/v0/event_registration/{id}/participants/self
|
---|---|
Content type | application/json
|
Method | PUT
|
Returns | JSON object: { "modified": "<whether the action resulted in any modification (bool)>" }
|
Registers the user as a participant to an event.
Parameters
editid
required | path |
ID of the event registration |
Request schema
editis_private
required | boolean |
Whether the registration should be private. |
answers
optional | array |
Answers to the participant questions enabled for this event. The IDs of available questions can be obtained with the #Get details of an event endpoint. Description and possible answers for those questions can then be obtained with the #Get available participant questions endpoint. The format of this parameter is the same used by the #Get your registration information endpoint: { "<question name>": { "value": "<value>", "other <(optional)>": "<additional text>" }, ... }
|
Responses
edit200 | Success |
---|---|
403 | The provided CSRF token does not match |
400 | The event registration is not open |
400 | The event has already ended |
400 | The event was deleted |
400 | The answers provided are malformed or otherwise invalid |
400 | The event was created on a different wiki to where the API was accessed |
403 | You cannot register for events |
404 | The given ID does not correspond to an existing event registration |
Cancel registration as a participant
editRoute | /campaignevents/v0/event_registration/{id}/participants/self
|
---|---|
Content type | application/json
|
Method | DELETE
|
Returns | JSON object: { "modified": "<whether the action resulted in any modification (bool)>" }
|
Cancels the registration as a participant to an event.
Parameters
editid
required | path |
ID of the event registration |
Responses
edit200 | Success |
---|---|
400 | The event has already ended |
403 | The provided CSRF token does not match |
400 | The event was deleted |
403 | You are not allowed to cancel your registration for this event |
404 | The given ID does not correspond to an existing event registration |
Remove participants from an event
editRoute | /campaignevents/v0/event_registration/{id}/participants
|
---|---|
Content type | application/json
|
Method | DELETE
|
Returns | JSON object: { "modified": "<number of removed participants (integer)>" }
|
Remove participant(s) from an event.
Parameters
editid
required | path |
ID of the event registration |
Request schema
edituser_ids
optional | array |
List of user ids to be removed, if omitted remove all. Passing an empty array will result in an error. |
Responses
edit200 | Success |
---|---|
400 | The event has already ended |
400 | user_ids is an empty array
|
400 | The event was deleted |
400 | The event was created on a different wiki to where the API was accessed |
403 | The provided CSRF token does not match |
403 | You are not allowed to remove participants for this event |
404 | The given ID does not correspond to an existing event registration |
Delete a registration
editRoute | /campaignevents/v0/event_registration/{id}
|
---|---|
Content type | application/json
|
Method | DELETE
|
Returns | Nothing |
Deletes an event registration.
Parameters
editid
required | path |
ID of the event registration |
Responses
edit204 | Success |
---|---|
400 | The event was created on a different wiki to where the API was accessed |
403 | The provided CSRF token does not match |
403 | You are not allowed to delete the registration |
404 | The given ID does not correspond to an existing event registration |
404 | The event registration is already deleted |
List the organizers of an event
editRoute | /campaignevents/v0/event_registration/{id}/organizers
|
---|---|
Content type | application/json
|
Method | GET
|
Returns | Array of objects: {
"organizer_id": "<organizer ID that can be passed as last_organizer_id>",
"user_id": "<central ID (integer)>",
"user_name": "<user name>",
"roles": [ "creator", "organizer", ... ],
"user_page": {
"path": "<url to the user page",
"title": "<url text for the user page link> ",
"classes": "<css classes for the user page link generated by core>"
},
}
|
Returns a list of organizers of a given event registration. This is hard-limited to 11 results.
Parameters
editid
required | path |
ID of the event registration |
last_organizer_id
optional | query |
Default null, if null get the first 11 organizers, if not null get next 11 organizers (this is not the user id) |
Responses
edit200 | Success |
---|---|
404 | The given ID does not correspond to an existing event registration |
List the participants of an event
editRoute | /campaignevents/v0/event_registration/{id}/participants
|
---|---|
Content type | application/json
|
Method | GET
|
Returns | Array of objects, where each one has the following shape:
{
"participant_id": "<participant ID that can be passed as last_participant_id>",
"user_id": "<central user ID>",
"user_registered_at": "<timestamp, in TS_MW format>",
"user_registered_at_formatted": "<human-readable timestamp, formatted according to the user preferences>",
"private": "<bool, whether the participant has registered privately>"
}
If the user is visible (and not deleted), the following properties will also be set: {
"user_name": "<user name>",
"user_page": {
"path": "<url to the user page",
"title": "<url text for the user page link> ",
"classes": "<css classes for the user page link generated by core>"
}
}
Additionally, if the user making the request is an organizer of the event, the following properties are also available: {
"user_is_valid_recipient": "<bool, whether the performer is allowed to send emails to this user via the extension.>",
"non_pii_answers": [
{
"message": "<string, the human-readable answer provided to this question, or a placeholder 'No response' value.>",
"questionID": "<integer, which identifies the question and matches the IDs used by the 'Get available participant questions' endpoint>"
}
]
}
If the participant's answers have already been aggregated, the value of the If the user is not visible, the response object will contain either |
Returns a list of participants of a given event registration. This is hard-limited to 20 results.
Parameters
editid
required | path |
ID of the event registration |
include_private required | query
|
Boolean, whether to include private participants in the result. The request will fail with a 403 error if the user is not allowed to view them. |
last_participant_id optional | query
|
Default null, if null get the first 20 participants, if not null get next 20 participants (this is not the user id) |
username_filter optional | query
|
String to filter participants by user_name |
exclude_users optional | query
|
Array of user ids to exclude from resultset |
Responses
edit200 | Success |
---|---|
403 | include_private is true, but the user is not allowed to view private participants
|
404 | The given ID does not correspond to an existing event registration |
Get details of an event
editRoute | /campaignevents/v0/event_registration/{id}
|
---|---|
Content type | application/json
|
Method | GET
|
Returns | JSON object with the same keys that you can use to edit a registration: {
"id": "<ID (integer)>",
"name": "<name>",
"event_page": "<event page title, prefixed with the localized namespace>",
"event_page_wiki": "<ID of the wiki where the event page is located (string)>",
"chat_url": "<url>",
"tracking_tools": [
{
"tool_id": "<ID of the tool>",
"tool_event_id": "<ID of the event within that tool>"
}
],
"status": "<status>",
"timezone": "<TZ of the event, in any format accepted by PHP's DateTimeZone>",
"start_time": "<timestamp in MW format, local time>",
"end_time": "<timestamp in MW format, local time>",
"online_meeting": "<whether the event is online (bool)>",
"inperson_meeting": "<whether the event is in-person (bool)>",
"meeting_url": "<url>",
"meeting_country": "<country>",
"meeting_address": "<address>",
"questions": "<array with the IDs of enabled participant questions (integers)>"
}
|
Returns the details of a given event registration.
Parameters
editid
required | path |
ID of the event registration |
Responses
edit200 | Success |
---|---|
404 | The given ID does not correspond to an existing event registration |
404 | The event registration was deleted |
Update the list of organizers
editRoute | /campaignevents/v0/event_registration/{id}/organizers
|
---|---|
Content type | application/json
|
Method | PUT
|
Returns | Nothing |
Updates the list of organizers of a given event registration.
Parameters
editid
required | path |
ID of the event registration |
Request schema
editorganizer_usernames
required | array |
A list of local usernames |
Responses
edit204 | Success |
---|---|
400 | organizer_usernames is an empty array
|
400 | The list of organizers is invalid, which may happen for several reasons: users do not have a global account, you're trying to add more than 10 organizers, users are not allowed to be organizers, or you are removing the event creator but you're not allowed to do that. |
400 | The event was created on a different wiki to where the API was accessed |
403 | You are not allowed to edit this event registration |
404 | The given ID does not correspond to an existing event registration |
Get your registration information
editRoute | /campaignevents/v0/event_registration/{id}/participants/self
|
---|---|
Content type | application/json
|
Method | GET
|
Returns |
{
"private": "<whether you are registered privately (bool)>",
"answers": {
"<question name>": {
"value": "<value of the chosen answer>",
"other <(optional)>": "<additional text for the chosen option>",
}
}
}
|
Returns the registration information of the current user as participant of a given event.
Parameters
editid
required | path |
ID of the event registration |
Responses
edit200 | Success |
---|---|
403 | You are not allowed to register for events |
404 | The given ID does not correspond to an existing event registration |
404 | The user does not participate in the given event |
Get available participant questions
editRoute | /campaignevents/v0/participant_questions
|
---|---|
Content type | application/json
|
Method | GET
|
Returns |
{
"<question ID (integer)>": {
"name": "<human-readable name of the question>",
"type": "<type of the question, one of 'radio', 'select', and 'text'>",
"label": "<localized label of the question>",
"options <(optional, only for radio and select)>": {
"<localized text of the option>": "<corresponding value (integer)>"
},
"other-options <(optional, and can only be present for radio and select types)>": {
"<option value for which this option is accepted (integer)>": {
"type": "<type of the option, can only be 'text'>",
"label": "<localized label of the option>"
}
}
}
}
|
Returns the list of available participant questions.
Parameters
editquestion_ids
optional | query |
Only include questions with the given IDs. Unrecognized IDs are ignored. |
Responses
edit200 | Success |
---|
Email participants
editRoute | /campaignevents/v0/event_registration/{id}/email
|
---|---|
Content type | application/json
|
Method | POST
|
Returns | {"sent": "<the number of sent emails>"}
|
Sends an email to the selected wiki users
Parameters
editid
required | path |
ID of the event registration |
invert_users
optional | body |
Boolean indicating whether to invert the selection of users, that is to select the provided user ids (false), or to select all participants except the provided user ids (true). Defaults to true. |
message
required | body |
The message body for the email, plaintext only |
subject
required | body |
The subject for the email |
user_ids
optional | body |
Array of user ids for the email recipients |
Responses
edit204 | Success |
---|---|
400 | You are blocked or throttled from sending email |
400 | The event was created on a different wiki to where the API was accessed |
400 | Please email participants on XXX, the wiki where the event was created. |
403 | The provided CSRF token does not match |
403 | You are not allowed to email participants |
404 | The given ID does not correspond to an existing event registration |