Other actions suggestions

[roipoussiere]

Following #1, we have this:

• PATCH ​/polls​/{pollId} Updates a poll
• DELETE ​/polls​/{pollId} Deletes a poll
• POST /polls/{pollId}/judgments​ Creates a judgment
• POST ​/polls/{pollId}/judges Invite a judge to a poll
• GET /polls​/{pollId}/results Get the results of a poll
• GET ​/judgments​/{judgmentId} Gets a judgment by ID
• DELETE /judgments​/{judgmentId} Deletes a judgment

I suggest some other actions:

Create a poll

First, I note the absence of:

POST ​/polls​ Creates a poll

Is it intentional?

Get a poll

GET ​/polls​/{pollId} Get a poll

To get meta data about a poll (all practical information but not the results): starting date, ending date, available grades, number of judges, etc.

Update a judgement

PATCH /judgments​/{judgmentId} Updates a judgment

(authorized only by the original judgment author)

Cancel a judgement

DELETE /judgments​/{judgmentId} Deletes a judgment

(authorized only by the original judgment author)

Get judges

GET ​/polls/{pollId}/judges Get information about judges of a poll

Useful to know who is invited and who already participated. This might be authorized only by poll author.

Remove a judge

DELETE ​/judges/{pollId}/judges/{judge-id} Deletes a judge from a poll

For transparency, this action could be publicly accessible from GET ​/polls​/{pollId}, although anonymized (ie. 2 judge invitations has been cancelled from this poll).

[guhur]

I don't understand about this:

First, I note the absence of: POST ​/polls​ Creates a poll Is it intentional?

This is right now in the spec

[guhur]

I like all of your other actions. Just I think we should add a lot of boolean parameters in the Poll model for dealing with them, such as:

• isJudgmentSettable
• isJudgmentDeletable
• isJudgeRemovable ...

It seems that most use case of a voting platform will not allow such actions (e.g., for the sake of simplicity) What do you think?

[guhur]

DELETE ​/judges/{pollId}/judges/{judge-id} Deletes a judge from a poll Why not just DELETE ​/judges/{judge-id}?

[roipoussiere]

I like all of your other actions. Just I think we should add a lot of boolean parameters in the Poll model for dealing with them, such as: isJudgmentSettable, isJudgmentDeletable, isJudgeRemovable, ...

It seems that most use case of a voting platform will not allow such actions (e.g., for the sake of simplicity)

Very good idea (although it should be is-judgment-settable, etc. if we use kebab-case convention).

I also suggest these parameters:

• realtime-results-visibilty: disabled (nobody) / private (only poll-author) / protected (participants only) / public (everyone)
• final-results-visibilty: private (only poll-author) / protected (participants only) / public (everyone)

Also, what is-judgment-settable should not be compatible with realtime-results-visibilty >=protected`.

DELETE ​/judges/{pollId}/judges/{judge-id} Deletes a judge from a poll Why not just DELETE ​/judges/{judge-id}?

Its more semantically correct because you don't delete the participant, you delete the ability for this participant to participate on this specific poll.

It also anticipates API evolution: imagine that in the future the API becomes user-based, where participants must create an account and log in to participate, DELETE ​/judges/{judge-id} will delete the member and `DELETE ​/judges/{pollId}/judges/{judge-id} will only delete its participation to a poll.

[guhur]

realtime-results-visibilty: disabled (nobody) / private (only poll-author) / protected (participants only) / public (everyone) final-results-visibilty: private (only poll-author) / protected (participants only) / public (everyone)

Names might be less standard, but can't we just merge the 2 options in one results-visibility:

• after-ending: nobody has the access until the end of the election;
• only-author: the poll-author has access all time long;
• only-participants: only the participants;
• public: everyone have access at any time.

[guhur]

Also, what is-judgment-settable should not be compatible with realtime-results-visibilty >= protected`.

Shouldn't be the front responsible to enforce this combination of settings? In rare occasions, one might want to create a completely free election?

[roipoussiere]

Names might be less standard, but can't we just merge the 2 options in one results-visibility:

I personally prefer to don't merge them for many reasons, I'm going to develop the main one:

Using predefined choices combinations of two distinct concepts is one (among many) vicious way to let developers decide for the users, although it's usually unwanted. As a developer I don't want to take the responsibility of choosing choices combinations based on some assumptions I just imagined in my developer brain, which is limited to my vision of the world.

It's like a restaurant where you just have to chose among predefined menus: 1. salad and carbonara pasta and ice-cream and coffee, OR 2. soup and vegetable pie and tiramisu and green tea. Maybe the cook thinks those are very good combinations, but there are many reasons that the cook don't imagine for one client to prefer other combinations.

[roipoussiere]

Also, what is-judgment-settable should not be compatible with realtime-results-visibilty >= protected`.

Shouldn't be the front responsible to enforce this combination of settings? In rare occasions, one might want to create a completely free election?

This kind of elections will allow participants to edit their vote based on current results. Such poll could be possible but in this case a warning should be added on the poll page that explicitly inform users about this behavior.

I'm not in favor of just checking on the client side: if we decide that it's not possible, it's not possible on the front and on the back. Otherwise we gives some superpowers to people that know how to makes curl requests.

[guhur]

Your two last messages sound contradictory to me:

As a developer I don't want to take the responsibility of choosing choices combinations based on some assumptions I just imagined in my developer brain, which is limited to my vision of the world.

I'm not in favor of just checking on the client side

Actually, I kinda disagree about this point:

This kind of elections will allow participants to edit their vote based on current results. Such poll could be possible but in this case a warning should be added on the poll page that explicitly inform users about this behavior.

Such use-case is for example Doodle. In a Doodle, you might looking for a date that satisfies everyone (not just the majority). Imagine that you are the only one that has a different date than the other users: in this case, you want to update your calendar to free a spot and then update your vote accordingly.

[roipoussiere]

Your two last messages sound contradictory to me

They share the same idea of limiting as much as possible the power given to developers and distribute it as much as possible to end users.

Such use-case is for example Doodle. In a Doodle, you might looking for a date that satisfies everyone (not just the majority).

Majority judgment is a tool to find a majority. If your objective is not to find the majority, then majority judgment is maybe not what you look for.

We can of course help people that want to use a majority judgment software to find other things than a majority, but it should not interfere the usability for other users. In this case, I think it can be dangerous for people that just want to use (and trust) MJ by what it was designed, because results can be biased.

[guhur]

They share the same idea of limiting as much as possible the power given to developers and distribute it as much as possible to end users.

That is also my point. We don't want to give too much powers to devs (deciding that a vote can't be changed after the user has seen the results), we want to allow the organizer deciding about it (setting is-judgment-settable and realtime-results-visibilty independantly).

I think we should close this issue, since the conversation is heading far from the original question.