I've gone through more of working through the API details based on the discussions. Here's what I propose. (Assuming that every Event Center user has an account on Meta, the wiki language/project isn't necessary. If that's not the case, then we'll need to add the wiki details as params as well.)

Relatively to the diagram, this adds event_id and removes wiki_language_prefix and wiki_project_domain.

endpoint 1: confirm_event_sync

This one corresponds to the 'Create Event Registration' event, establishing that a particular Event Center event will be responsible for the participant list of a particular Dashboard Course.

POST /wikimedia_event_center/confirm_event_sync as JSON
{
 "course_slug": string // the unique URL slug for the Course
 "event_id": string or integer // a unique ID for the Event Center event
 "organizer_username": string // the username of the Event Center event's organizer.
                              // Must match a user in the "facilitator" role for the Course.
 "secret": string // shared secret between the Event Center and the Dashboard
}

On failure, returns a JSON object with the error message and error code.
Possible error codes:

invalid_secret - The shared secret doesn't match
course_not_found - A Course with the provided slug doesn't exist
not_organizer - The organizer username doesn't match a user in the "facilitator" role
already_in_use - The course already has participants, so it can't be linked to the event
sync_already_enabled - The course is already linked to an event

endpoint 2: update_event_participants

This is for any time users are added or removed from an event, to push the latest participant list to the Dashboard Course.

POST /wikimedia_event_center/update_event_participants as JSON
{
 "course_slug": string // the unique URL slug for the Course
 "event_id": string or integer // a unique ID for the Event Center event
 "organizer_username": string // the username of the Event Center event's organizer.
                              // Must match a user in the "facilitator" role for the Course.
 "secret": string // shared secret between the Event Center and the Dashboard
 "participant_usernames": array of strings // usernames of event's current participants
}

Possible error codes:

invalid_secret - The shared secret doesn't match
course_not_found - A Course with the provided slug doesn't exist
not_organizer - The organizer username doesn't match a user in the "facilitator" role
sync_not_enabled - This Course isn't linked to the Event Center event (based on event_id)

@cmelo please have look at my proposed API signatures when you have a chance. If these look good, I'm ready to implement them.

HI @Ragesoss, thanks for the detailed information, it sounds good for the MVP.

I've deployed this to a test server, dashboard-testing.wikiedu.org, and can provide the API secret whenever the team is ready to start testing out integration.

This is great, thank you so much @Ragesoss

Hi all, do we expect this epic to contain more than two tasks, or is that the complete scope for P&E Dashboard integration for v1? (barring any bugs that need resolving in QA and beyond, of course.)
Wondering for sprint planning/estimation tomorrow.

In T302584#8218795, @ldelench_wmf wrote:

Hi all, do we expect this epic to contain more than two tasks, or is that the complete scope for P&E Dashboard integration for v1? (barring any bugs that need resolving in QA and beyond, of course.)
Wondering for sprint planning/estimation tomorrow.

The 2 subtasks are only for building the base logic that we need in our backend. We will definitely need more tasks for the complete P&E Dashboard integration, but I'm unsure about the details.

Hi @Ragesoss, I was reading the above and trying to understand how the API will work, and I have some additional questions:

• Organizers can also delete event registrations (and, in the future, restore them). Do we need to do anything special if that happens? It's not mentioned in the endpoint description above, but I was wondering if it's something that should be added
• Soon we will add support for adding multiple organizers to an event. Is this something that we can integrate with the P&E dashboard?
• Very soon we will add an option for participants to register anonymously (i.e., only organizers can see their names in the list of participants). Is there any specific precaution that we need to take when using the update_event_participants endpoint in this scenario?

Thanks in advance.

@Daimona:

• Organizers can also delete event registrations (and, in the future, restore them). Do we need to do anything special if that happens? It's not mentioned in the endpoint description above, but I was wondering if it's something that should be added

I think these should probably be independent at this point. It will make sense to add deletion-handling at the same time we add the option to create a Dashboard event automatically via Event Center, but in the meantime, since Dashboard events are created independently, users may want to delete an event registration but still use the Dashboard for their event.

• Soon we will add support for adding multiple organizers to an event. Is this something that we can integrate with the P&E dashboard?

I'll need to extend the API so that in accepts a set of organizers in addition to the set of participants. The Dashboard already supports multiple organizers, so it shouldn't be too hard. (However, this is outside the v1 scope that we had planned.)

• Very soon we will add an option for participants to register anonymously (i.e., only organizers can see their names in the list of participants). Is there any specific precaution that we need to take when using the update_event_participants endpoint in this scenario?

The Dashboard has support for 'private' events, but I think we would need to talk through the privacy features on both sides to figure out whether they are compatible enough that it makes sense to allow syncing in this scenario. I'm guessing the answer is 'no', because participants in a private event on the Dashboard can see all the other participants; the event just can't be seen by any non-Dashboard-admin who isn't already part of the event.

In T302584#8234582, @Ragesoss wrote:

@Daimona:

• Organizers can also delete event registrations (and, in the future, restore them). Do we need to do anything special if that happens? It's not mentioned in the endpoint description above, but I was wondering if it's something that should be added

I think these should probably be independent at this point. It will make sense to add deletion-handling at the same time we add the option to create a Dashboard event automatically via Event Center, but in the meantime, since Dashboard events are created independently, users may want to delete an event registration but still use the Dashboard for their event.

OK thank you, sounds good to me.

• Soon we will add support for adding multiple organizers to an event. Is this something that we can integrate with the P&E dashboard?

I'll need to extend the API so that in accepts a set of organizers in addition to the set of participants. The Dashboard already supports multiple organizers, so it shouldn't be too hard. (However, this is outside the v1 scope that we had planned.)

Sorry, I don't know what the previous agreement were and what was planned for V1, apologies if this wasn't on your radar. At any rate, I wasn't really asking for the possibility of adding multiple organizer to the dashboard with an API endpoint. I asked that because organizer_username is a required parameter for both endpoints, and I was trying to understand what value we should pass in case of multiple organizers in order to pass authorization checks. I think for now we could just pass the username of the event creator (assuming they are also a facilitator for that event in the dashboard) and it should just work.

• Very soon we will add an option for participants to register anonymously (i.e., only organizers can see their names in the list of participants). Is there any specific precaution that we need to take when using the update_event_participants endpoint in this scenario?

The Dashboard has support for 'private' events, but I think we would need to talk through the privacy features on both sides to figure out whether they are compatible enough that it makes sense to allow syncing in this scenario. I'm guessing the answer is 'no', because participants in a private event on the Dashboard can see all the other participants; the event just can't be seen by any non-Dashboard-admin who isn't already part of the event.

Got it, thank you. Also, for the record, we're working on this "very soon" because after some conversations we had with Trust & Safety, this came out as a (kinda-)necessary feature for V1 and we decided to build it immediately. I think we can keep that in mind and avoid syncing "anonymous participants" with the dashboard, but there's no need to make a decision now. I left a note at T316405 so that we can think about it later on.

@Daimona:

Sorry, I don't know what the previous agreement were and what was planned for V1, apologies if this wasn't on your radar. At any rate, I wasn't really asking for the possibility of adding multiple organizer to the dashboard with an API endpoint. I asked that because organizer_username is a required parameter for both endpoints, and I was trying to understand what value we should pass in case of multiple organizers in order to pass authorization checks. I think for now we could just pass the username of the event creator (assuming they are also a facilitator for that event in the dashboard) and it should just work.

Thanks, that's very helpful contxt. In the current version, organizer_username needs to be a user who is already listed as an organizer on the Dashboard (but any organizer would be fine). It's only used to verify that the user at the Event Center side is also a user who has control of the event on the Dashboard side. If we don't care (for now) about syncing a whole set of organizers from Event Center to the Dashboard, it would be a very easy change to change the organizer_username parameter to organizer_usernames, and then Event Center could send any number of organizer usernames, and the Dashboard would just verify that at least one of those users is also in the relevant role on the Dashboard.

In T302584#8234763, @Ragesoss wrote:

@Daimona:

Sorry, I don't know what the previous agreement were and what was planned for V1, apologies if this wasn't on your radar. At any rate, I wasn't really asking for the possibility of adding multiple organizer to the dashboard with an API endpoint. I asked that because organizer_username is a required parameter for both endpoints, and I was trying to understand what value we should pass in case of multiple organizers in order to pass authorization checks. I think for now we could just pass the username of the event creator (assuming they are also a facilitator for that event in the dashboard) and it should just work.

Thanks, that's very helpful contxt. In the current version, organizer_username needs to be a user who is already listed as an organizer on the Dashboard (but any organizer would be fine). It's only used to verify that the user at the Event Center side is also a user who has control of the event on the Dashboard side. If we don't care (for now) about syncing a whole set of organizers from Event Center to the Dashboard, it would be a very easy change to change the organizer_username parameter to organizer_usernames, and then Event Center could send any number of organizer usernames, and the Dashboard would just verify that at least one of those users is also in the relevant role on the Dashboard.

Makes sense, I think this is a possibility. We're starting work on this epic now, so I guess we won't get to actually using the API until next week, which means we still have some time to figure out the long-term plan with Ilana.

Now that we have a requirement to allow confidential registration (T316405), we need to think about how the dashboard integration will handle it. For example, this question:

In T318369#8261329, @ifried wrote:

@Ragesoss @cmelo Hello! If someone registers as public and then changes to private, can we remove their username from the dashboard? And how about if someone joins as private and decides to be public?

In T302584#8269164, @vyuen wrote:

Now that we have a requirement to allow confidential registration (T316405), we need to think about how the dashboard integration will handle it. For example, this question:

In T318369#8261329, @ifried wrote:

@Ragesoss @cmelo Hello! If someone registers as public and then changes to private, can we remove their username from the dashboard? And how about if someone joins as private and decides to be public?

I think we mostly covered this in our last meeting, with the key points added to T317707. In short, we'll only send public participants to the dashboard, so it should work just fine as long as we send an update to the dashboard when the visibility of a participant changes.

@Ragesoss Hi, I have one more question about the endpoints at T302584#7751395. We already talked about replacing the "organizer_username" parameters with "organizer_usernames", that accept a list instead of a single name. I still think that would be a good solution for the confirm_event_sync endpoint, but I'm wondering if the parameter is necessary for the update_event_participants endpoint. Requests to that endpoint are made whenever the list of participants changes, which in most cases is an action initiated by the participants themselves. So I'm not sure if we need any authorization checks for that step, unless I'm missing something. What do you think?

In T302584#8307540, @Daimona wrote:

@Ragesoss Hi, I have one more question about the endpoints at T302584#7751395. We already talked about replacing the "organizer_username" parameters with "organizer_usernames", that accept a list instead of a single name. I still think that would be a good solution for the confirm_event_sync endpoint, but I'm wondering if the parameter is necessary for the update_event_participants endpoint. Requests to that endpoint are made whenever the list of participants changes, which in most cases is an action initiated by the participants themselves. So I'm not sure if we need any authorization checks for that step, unless I'm missing something. What do you think?

Yes, I agree. I don't see any reason why we couldn't remove that parameter from update_event_participants. Should I implement this change? I can likely do both the organizer_usernames change and removal of that parameter in the next couple of days.

In T302584#8308550, @Ragesoss wrote:

In T302584#8307540, @Daimona wrote:

@Ragesoss Hi, I have one more question about the endpoints at T302584#7751395. We already talked about replacing the "organizer_username" parameters with "organizer_usernames", that accept a list instead of a single name. I still think that would be a good solution for the confirm_event_sync endpoint, but I'm wondering if the parameter is necessary for the update_event_participants endpoint. Requests to that endpoint are made whenever the list of participants changes, which in most cases is an action initiated by the participants themselves. So I'm not sure if we need any authorization checks for that step, unless I'm missing something. What do you think?

Yes, I agree. I don't see any reason why we couldn't remove that parameter from update_event_participants. Should I implement this change? I can likely do both the organizer_usernames change and removal of that parameter in the next couple of days.

Sure, thank you! I'm still finishing some preliminary work for the general tracking tools logic, and I'd expect to start working on the P&E integration in the upcoming days.

I've made these updates and deployed it to dashboard-testing.wikiedu.org.

For now, you can either send or not send organizer_usernames as part of update_event_participants. It doesn't currently do anything with those usernames (since it no longer checks for whether the organizer identity matches), but later it will be used for updating the set of Dashboard facilitators, once Event Center supports having multiple organizers and those need to be sync'ed along with the participants list.

I've just deployed an update to staging:

• Added the unsync_event endpoint
• Added the dry_run parameter to all three endpoints. Don't include this parameter except when you want to verify that the action is going to work; when used, no changes will take place on the Dashboard end of things, but it should return the same error code as a real call would if there's a problem, and will return 200 without doing anything to the Dashboard database if everything seems to be in order.