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
[edit]Route | /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
[edit]event_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 |
wikis
required | array |
List of wiki IDs that this event focuses on, e.g. [ "enwiki", "frwiki" ] . Up to 100 IDs can be specified. Pass an empty array if the event does not focus on any wikis. Pass the special value [ "*" ] if the event is open to all wikis.
|
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
[edit]201 | 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
[edit]Route | /campaignevents/v0/event_registration/{id}
|
---|---|
Content type | application/json
|
Method | PUT
|
Returns | Nothing |
Edits an event registration.
Parameters
[edit]id
required | integer |
ID of the event registration |
Request schema
[edit]event_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 |
wikis
required | array |
List of wiki IDs that this event focuses on, e.g. [ "enwiki", "frwiki" ] . Up to 100 IDs can be specified. Pass an empty array if the event does not focus on any wikis. Pass the special value [ "*" ] if the event is open to all wikis.
|
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
[edit]204 | 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
[edit]Route | /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
[edit]userid
required | integer |
The central user ID of the organizer |
Responses
[edit]201 | Success: list all the events. |
---|---|
404 | The user does not exist. |
List all events a participant has registered for
[edit]Route | /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
[edit]userid
required | integer |
The central user ID of the participant |
Responses
[edit]201 | Success: list all the events. |
---|---|
404 | The user does not exist. |
Register as a participant
[edit]Route | /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
[edit]id
required | path |
ID of the event registration |
Request schema
[edit]is_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
[edit]200 | 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
[edit]Route | /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
[edit]id
required | path |
ID of the event registration |
Responses
[edit]200 | 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
[edit]Route | /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
[edit]id
required | path |
ID of the event registration |
Request schema
[edit]user_ids
optional | array |
List of user ids to be removed, if omitted remove all. Passing an empty array will result in an error. |
Responses
[edit]200 | 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
[edit]Route | /campaignevents/v0/event_registration/{id}
|
---|---|
Content type | application/json
|
Method | DELETE
|
Returns | Nothing |
Deletes an event registration.
Parameters
[edit]id
required | path |
ID of the event registration |
Responses
[edit]204 | 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
[edit]Route | /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
[edit]id
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
[edit]200 | Success |
---|---|
404 | The given ID does not correspond to an existing event registration |
List the participants of an event
[edit]Route | /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
[edit]id
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
[edit]200 | 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
[edit]Route | /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>",
"wikis": [ "<list of wiki IDs, or the special value `*` for all wikis>" ],
"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
[edit]id
required | path |
ID of the event registration |
Responses
[edit]200 | Success |
---|---|
404 | The given ID does not correspond to an existing event registration |
404 | The event registration was deleted |
Update the list of organizers
[edit]Route | /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
[edit]id
required | path |
ID of the event registration |
Request schema
[edit]organizer_usernames
required | array |
A list of local usernames |
Responses
[edit]204 | 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
[edit]Route | /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
[edit]id
required | path |
ID of the event registration |
Responses
[edit]200 | 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
[edit]Route | /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
[edit]question_ids
optional | query |
Only include questions with the given IDs. Unrecognized IDs are ignored. |
Responses
[edit]200 | Success |
---|
Email participants
[edit]Route | /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
[edit]id
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
[edit]204 | 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 |