The /merit-profile endpoint

[roipoussiere]

Currently, the merit profile is displayed in the result page as an html table.

I suggest an other behavior to facilitate the mv-api integration with other services: adding a dedicated /merit-profile endpoint on the api, that returns the merit profile as an image.

In this way, any service could get and display the image of the merit profile by a simple url call.

I'm currently working on a Python module that generates a such image, that can be used when finished in the mv-api or any Python-related project, which will be callable and via the CLI.

Note that this module (and so the /merit-profile endpoint) does not process MJ data, it only render the results.

Verb used

GET

Parameters

results

Results for each proposal. Results length for each candidate must be equals to mentions length and result sum of each candidate must be equals between them.

• type: dict[string: array[int]]
• mandatory
• example: candidate1:21-14-32;candidate2:12-16-39

width

The image width.

• type: integer
• default: 400
• min: 100
• max: 1200

legend

Define how to include the legend that displays the mentions.

• type: enum
• options: no, top, bottom
• default: bottom

labels

Define how to include the labels that displays the proposals / candidates. top / bottom use references (like in the current merit profile), left / right include them directly beside the graph in a sidebar.

• type: enum
• options: no, top, bottom, left, right
• default: top

sidebar_width

Define the width of the sidebar, in percents of the image width. If there is no enough place to fully display a label, the label will be stripped. Has no effect if labels is set to no, top or bottom.

• type: integer
• min: 5
• max: 50
• default: 25

mentions

The list of mentions that will be used in labels (also used to define the number of mentions).

• type: array[string]
• default: ['reject', 'insufficient', 'poor', 'fair', 'good', 'very good', 'excellent']

hints

Define how values are displayed inside merit profile mentions.

• type: enum
• options: no, percents, number
• default: no

median

Define how the median line must be displayed.

• type: enum
• options: no, dotted, solid
• default: dotted

extention

Define the extension of the merit profile image. Svg is useful when sharing on websites of forums, png is useful for OpenGraph integration.

• type: enum
• options: svg, png
• default: png

[guhur]

Could you define the use-case for using this endpoint? I am not really sure I understand.

For example, I think that if you want to get a graph representation, you would generally want to rank the candidates on the graph according to MJ sorting.

In this case, I think the following procedure is simpler:

1. Create a poll with POST /polls,
2. Inject your results inside POST /polls/{poll-id}/judgments.
3. Ask for the figure: GET /polls/{poll-id}/figure.

Such workflow avoids :

• another endpoint names ;
• mixing parameters of the figure and the results of the poll ;
• using new schemas (candidate1:21-14-32;candidate2:12-16-39 is sensibly different from current schemas, which might be annoying for clients).

[roipoussiere]

Could you define the use-case for using this endpoint?

• facilitate the integration with other services (forums, social medias, etc.).
• simulate an election for learning purpose, without having to create a poll and add proposals one by one;
• if when MJ will become widely used, then there will be many tools to create elections and this kind of endpoint can be used to fact-check the result.

For example, I think that if you want to get a graph representation, you would generally want to rank the candidates on the graph according to MJ sorting.

Nether though about this but it's a nice idea.

Ask for the figure: GET /polls/{poll-id}/figure.

Good point, this is indeed simpler and all workflows to avoids you described make sense.

But one thing to be aware is that if you share results images and then delete the poll, all those images will become broken links. A poll-agnostic endpoint can prevent this.

[guhur]

But one thing to be aware is that if you share results images and then delete the poll, all those images will become broken links. A poll-agnostic endpoint can prevent this.

That's why we need to clarify your use-case. In my opinion, if I want to delete a poll (e.g. I discover that someone cheated), I want to make sure that every chart of the results explains that this poll has been invalidated.

all those images will become broken links

Not necessarily. We can delete all the information about the poll itself, but keep the poll id in the database and toggle a "deleted-poll" boolean. This would allow us to display "this poll has been deleted by its organizer".