Extension:CampaignEvents/Api

From mediawiki.org

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
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
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 "event_deleted": true element.

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 "event_deleted": true element.

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]

When using this endpoint on Wikimedia projects, you agree to the Terms of Use, Privacy Policy, Universal Code of Conduct, and any local Friendly Space Policy provided by the event organizers.
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 non_pii_answers property is a string with a message explaining why the answers have already been aggregated.

If the user is not visible, the response object will contain either "hidden": true or "not_found": true for accounts that have been hidden or couldn't be found, respectively.

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>",
  "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
Retrieved from "https://www.mediawiki.org/w/index.php?title=Extension:CampaignEvents/Api&oldid=6470818"