Page MenuHomePhabricator

๐Ÿฆ Create/replace a sitelink to an item on a given wiki
Open, Needs TriagePublic13 Estimated Story Points

Description

Description
PUT entities/items/{item_id}/sitelinks/{site_id}

Request payload:

{
  "sitelink": {
    "title": ...,
    "badges": [ Q-ID, ... ] (optional)
  },
  "comment": ... (optional)
  "tags": [ ... ] (optional)
  "bot": false (optional)
}

Acceptance criteria:

  • The respective successful responses should present the relevant data as a JSON object -- similar to the responses of GET /entities/items/{item_id}/sitelinks/{site_id}.
  • If a sitelink in the given wiki didn't exist before the successful request the response should use 201 code.
  • If the request changed the existing sitelink, the response code should be 200.
  • If the request payload contains the URL, it is ignored (and not rejected)

Error cases to consider

HTTP response coderesponse payload
Item does not exist 404 "code": "item-not-found"
"message": "Could not find an item with the ID: {item_id}"
Invalid item ID 400 "code": "invalid-item-id"
"message": "Not a valid item ID: {item_id}"
Invalid site ID 400 { "code": "invalid-site-id", "message": "Not a valid site ID: {site_ID}"}
Invalid edit tag400 { "code": "invalid-edit-tag", "message": "Invalid MediaWiki tag: {tag}" }
Comment too long400 {"code": "comment-too-long", "message": "Comment must not be longer than {limit} characters"}
sitelink title field not provided400{ "code": "sitelink-data-missing-title", "message": "Mandatory sitelink title missing"}
title is empty400 {"code": "title-field-empty", "message": "Title must not be empty"}
Invalid title400 {"code": "invalid-title-field", "message": "Not a valid input for title field'"}
value provided as a badge is not an item ID400{"code": "invalid-input-sitelink-badge", "message": "Badge input is not an item ID: {value}"}
item provided is not allowed as a site link badge 400{"code": "item-not-a-badge", "message": "Item ID provided as badge is not allowed as a badge: {item_id}"}
value of badges field is not a list400{"code": "invalid-sitelink-badges-format", "message": "Value of badges field is not a list" }
Title does not exist on given site400{"code": "title-does-not-exist", "message": "Page with title {title} does not exist on the given site" }
Item redirect409{"code": "redirected-item", "message": "Item {item_id} has been merged into {other_id}"}
Sitelink conflict409{"code": "sitelink-conflict", "message": "Sitelink is already being used on {other_item_id}", "context": {"item-id": "{other_item_id}"}

Notes

  • Automated edit summaries to be of the form:
    • if the edit resulted in adding a site link to a wiki which was not connected before, and no badges: /* wbsetsitelink-add:1|SITE_ID */ TITLE
    • if the edit resulted in adding a site link to a wiki which was not connected before, and there are badges: /* wbsetsitelink-add-both:2|SITE_ID */ TITLE, BADGE_ITEMS_FORMATTED
    • if the edit resulted in setting a title to a different page on a wiki which has been connected as a site link before, and there are no badges: /* wbsetsitelink-set:1|SITE_ID */ TITLE
    • if the edit resulted in setting a title to a different page on a wiki which has been connected as a site link before, and there are badges: /* wbsetsitelink-set-both:2|SITE_ID */ TITLE, BADGE_ITEMS_FORMATTED
    • if the edit resulted in changes badges of an existing sitelink (and not change the title): /* wbsetsitelink-set-badges:1|SITE_ID */ BADGE_ITEMS_FORMATTED
    • where BADGE_ITEMS_FORMATTED is a comma-separated list of wikitext links to item pages
    • see Wikibase\Repo\ChangeOp\ChangeOpSiteLink class, and surrounding classes, for further details of the existing Wikibase automated edit summary logic
  • client can provide additional edit metadata: mediawiki tags, edit summary text to append to the automated summary, and a bot edit flag, like in PUT /entities/items/{item_id}/labels/{language_code}
  • Handle HTTP conditional request headers as in PUT /entities/items/{item_id}/statements
  • Handle user authentication/authorization like in PUT /entities/items/{item_id}/statements

Additional notes:

How Action API handles it: https://www.wikidata.org/w/api.php?action=help&modules=wbsetsitelink

Task breakdown notes:

  • Add the new route to OAS
  • happy path (with empty edit summary)
    • including ETag and Last-Modified headers
    • create SiteLinkDeserializer
    • differentiate 200/201
  • validate sitelink badges
  • validate sitelink title
    • skip title existence check
  • validate title existence
  • Implement edit summaries
  • handle sitelink conflict
  • Respond 404/409 if item not found/redirect
  • Authorization
  • Use the usual middlewares and add the route handler to RouteHandlersTest
  • Add spec tests.
  • Mark as production ready.

Related Objects

Event Timeline

Ifrahkhanyaree_WMDE renamed this task from Add/replace a sitelink to an item to Create/replace a sitelink to an item.Oct 9 2023, 2:34 PM
Ifrahkhanyaree_WMDE updated the task description. (Show Details)
Ifrahkhanyaree_WMDE renamed this task from Create/replace a sitelink to an item to Create/replace a sitelink to an item on a given wiki.Oct 9 2023, 3:26 PM
Ifrahkhanyaree_WMDE added a project: Story.
Ifrahkhanyaree_WMDE updated the task description. (Show Details)
Ifrahkhanyaree_WMDE renamed this task from Create/replace a sitelink to an item on a given wiki to To edit: Create/replace a sitelink to an item on a given wiki.Jan 4 2024, 1:53 PM
Ifrahkhanyaree_WMDE updated the task description. (Show Details)
Ifrahkhanyaree_WMDE renamed this task from To edit: Create/replace a sitelink to an item on a given wiki to Create/replace a sitelink to an item on a given wiki.Jan 4 2024, 3:55 PM
Jakob_WMDE renamed this task from Create/replace a sitelink to an item on a given wiki to ๐Ÿฆ Create/replace a sitelink to an item on a given wiki.Jan 24 2024, 11:38 AM

@Ifrahkhanyaree_WMDE @WMDE-leszek, @Dima noticed that the invalid-item-id 400 error response has a context property. I think this is a mistake in the story description, as all the invalid-item-id responses from other endpoints don't contain a context property.