Describe all the actions that can be taken with Jade via the MediaWiki API
Description
Details
Project | Branch | Lines +/- | Subject | |
---|---|---|---|---|
mediawiki/extensions/Jade | master | +231 -0 | jsonschema: add v1 proposal schema |
Status | Subtype | Assigned | Task | ||
---|---|---|---|---|---|
Open | None | T212435 Review real-world query plans and performance for Jade | |||
Open | None | T238877 Write Huggle labels to Jade | |||
Resolved | calbon | T183381 Deploy pilot of Jade to a small set of wikis. | |||
Resolved | ACraze | T229967 Complete Jade documentation | |||
Resolved | ACraze | T229968 Write Jade extension documentation | |||
Resolved | ACraze | T199834 Implement a MW API module for interacting with Jade entities | |||
Duplicate | ACraze | T217904 Write API contract for Jade | |||
Resolved | None | T199519 Write user-facing documentation for Jade | |||
Resolved | Halfak | T204905 Write glossary of JADE concepts | |||
Resolved | ACraze | T253230 Write UI walk-through for Jade user-facing documentation | |||
Resolved | ACraze | T242008 Write Jade documentation for secondary integrations | |||
Resolved | kevinbazira | T253232 Add a link to [[mw:Jade]] within the information dialog/tooltip for a facet | |||
Resolved | ACraze | T244152 Jade local dev setup / README docs |
Event Timeline
@Halfak here is a first attempt at the API spec, based on all the notes and wire frames:
https://etherpad.wikimedia.org/p/jade_api_spec
Also, here is an updated schema with a few minor changes (mostly renaming judgement to label and adding a unique identifier):
https://etherpad.wikimedia.org/p/jade_schema_v2
I think a good next step for the updated schema is to submit a patchset to gerrit. I can review and approve there.
Otherwise, the Jade API spec looks good at first glance. I'm going to spend some time with the schema and some of the wireframes before I fully sign off.
OK. I've created a new iteration on the schema. https://etherpad.wikimedia.org/p/jade_schema_v3
I solved a few problems where we were using "oneOf"s that would have allowed for mismatched data. I also simplified situations where we get something like {"type": "contentquality", "proposals": {"schema": {"contentquality": 3 so that it is now just "contentquality": {"proposals": {"data": 3. Less duplication.
I also managed reducing some DRY issues by implementing a base "proposal" schema and then implementing the differences between contentquality and editquality (just the "data" field). Look for the use of "allOf" in #/definitions/proposals/...
Otherwise, I made an aesthetics-based judgment call to make the list of "facets" a map (object) instead.
See also updates to https://www.mediawiki.org/wiki/JADE/Glossary
Biggest change is that a collection of "proposals" is now called a facet. I like the word "facet" because it means both an aspect of a thing and also a flat surface of a gem (and Jade is a gem).
Re. the API spec. I wonder if we can limit our endpoints and handle most of the logic for the user. E.g. if a user calls action=jadePropose, there are four possible states:
- The entity page doesn't exist at all.
- Create the page, the relevant proposal and add an endorsement from the user.
- Set the preferred bit to point to the new proposal.
- The entity page exists but no matching proposed label.
- Create the relevant proposal and add an endorsement from the user.
- If another proposal exists for the target facet, leave the preferred bit alone otherwise, set the bit.
- The entity page exists and there's a proposed label with matching data.
- Add an endorsement to the relevant proposal and leave preference alone.
- A warning is returned to the user if they specified a comment and a comment is already present in the proposal.
- The user already has an endorsement for this facet but it is for a different proposal.
- Move the user's endorsement from the other proposal to the target proposal, creating it if necessary.
- If the other proposal was preferred but now has no more endorsements, move the preference bit as well.
For this endpoint, we'd need to match the data of the request with the data of proposals. We'll also need to know what facet they are aiming to affect.
action=jadePropose description: @param entity_type (str) // the type of entity (revision/diff/etc.) [required] @param entity_id (number) // the ID of the entity [required] @param data (str) JSON encoded target data ex: {'goodfaith': (bool) 'damaging': (bool)} [required] @param comment (string) @param notes (string) @param token (string) [required] returns: entity w/ single proposed label + endorsement (json)
What do you think of this type of pattern? Is this crazy?
BTW, my main motivation for this proposal is to make work for 3rd party tool devs as easy as possible. It would be nice if they could call a single endpoint with the same data and have the most reasonable thing happen without having to implement a ton of logic.
E.g. A user is using Huggle to review edits. That user flags an edit as bad. Huggle makes a simple API call for the entity with {damaging: true, goodfaith: false} and the right thing just happens regardless of the state of the entity page.
@Halfak this approach makes sense. I believe we can implement a single API module that determines the context of each request and then calls methods to handle each case. Also, I think we'll need to include a couple more parameters to action=jadePropose for handling actions like setting a preferred label and deleting stuff. I'll try and map out all of those tomorrow.
I think the updated schema looks good as well, 'facet' seems like a good name for a collection of proposals. I'll add it as a patchset to gerrit.
I just made some notes on the patch and updated the etherpad with the new "created" field per our discussion.
Change 525699 had a related patch set uploaded (by Accraze; owner: Accraze):
[mediawiki/extensions/Jade@master] jsonschema: add v1 proposal schema
Change 525699 merged by Halfak:
[mediawiki/extensions/Jade@master] jsonschema: add v1 proposal schema
Looks like the above patch was really for T229355: Simplify and extend JADE content schema (based on API spec insights)