As a tool builder I want to be able to edit sitelinks so that the work in my tool can be saved back to Wikidata.
PATCH /entities/items/{item_id}/sitelinks
Notes:
- The request contains a JSON body with a mandatory patch key containing a JSON Patch document plus optional metadata: tags, bot, comment.
- Response body containing the updated sitelinks data, using the similar structure as GET /entities/items/{item_id}/sitelinks.
- Handle HTTP conditional request headers as in PUT .../sitelinks/{site_id}
- Handle user authentication/authorization like in PUT .../sitelinks/{site_id}
- All edit data is validated
Autocomments:
- should mimic the behavior of wbeditentity when editing sitelinks
- Automated edit summaries to be of the form: /* wbeditentity-update:0| */
Error cases considered:
| HTTP response code | response 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}" "context": {"item": "{item-id}"} |
| Invalid edit tag | 400 | { "code": "invalid-edit-tag", "message": "Invalid MediaWiki tag: {tag}" } |
| Comment too long | 400 | {"code": "comment-too-long", "message": "Comment must not be longer than {limit} characters"} |
| Item with the provided ID has been redirected to another item | 409 | "code": "redirected-item" "message": "Item {item_id} has been merged into {other_id}." |
| Invalid JSON patch (general error) | 400 | "code": "invalid-patch" "message": "The provided patch is invalid" |
| incorrect JSON patch operation | 400 | "code": "invalid-patch-operation" "message": "Incorrect JSON patch operation: '<op>'" "context": { "operation": <operation_object> } |
| invalid field type in JSON patch (either of op, path, from is not a string) | 400 | "code": "invalid-patch-field-type" "message": "The value of '<field>' must be of type string" "context": { "operation": <operation_object>, "field": <field> } |
| missing mandatory field in JSON patch (op, path, value, also from on copy/move patches) | 400 | "code": "missing-json-patch-field" "message": "Missing '<field>' in JSON patch" "context": { "operation": <operation_object>, "field": <field> } |
| Target of JSON Patch not found on the object | 409 | "code": "patch-target-not-found", "message": "Target '<target>' not found on the resource", "context": { "operation": <operation_object>, "field": <path> } |
| JSON Patch test operation failed | 409 | "code": "patch-test-failed", "message": "Test operation in the provided patch failed. At path '{path}' expected '{expected}', actual: '{actual}'", "context": { "operation": <operation_object>, "actual-value": <actual> } |
| After applying a patch, invalid site ID is used | 422 | {"code": "patched-sitelinks-invalid-site-id", "message": "Not a valid site ID {site_id} in patched sitelinks", "context": { "site_id": "{site_id}" } } |
| After applying a patch, no sitelink title provided | 422 | {"code": "patched-sitelink-missing-title", "message": "No sitelink title provided for site {site_id} in patched sitelinks", "context": { "site_id": "{site_id}" } } |
| After applying a patch, sitelink title is empty | 422 | {"code": "patched-sitelink-title-empty", "message": "Sitelink cannot be empty for site {site_id} in patched sitelinks", "context": { "site_id": "{site_id}" } } |
| After applying a patch, sitelink title is invalid | 422 | {"code": "patched-sitelink-invalid-title", "message": "Invalid sitelink title {title} for site {site_id} in patched sitelinks", "context": { "site_id": "{site_id}", "title": "{title}" } } |
| After applying a patch, page with given title does not exist | 422 | {"code": "patched-sitelink-title-does-not-exist", "message": "Incorrect patched sitelinks. Page with title {title} does not exist on site {site_id}", "context": { "site_id": "{site_id}", "title": "{title}" } } |
| After applying a patch, a sitelink badge value is not an item ID | 422 | {"code": "patched-sitelink-invalid-badge", "message": "Incorrect patched sitelinks. Badge value {badge} for site {site_id} is not an item ID", "context": { "site_id": "{site_id}", "badge": "{badge}" } } |
| After applying a patch, the sitelink added to item is in conflict with another item | 422 | {"code": "patched-sitelink-conflict", "message": "Site {site_id} is already being used on {other_item_id}", "context": {"matching-item-id": "{other_item_id}", "site": "{site_id}"} |
| After applying a patch, the URL is modified | 422 | {"code": "url-not-modifiable", "message": "URL of sitelink cannot be modified","context": { "site": <site_id> }} |
| After applying a patch, a item used as a sitelink badge is not allowed as a badge | 422 | {"code": "patched-sitelink-item-not-a-badge", "message": "Incorrect patched sitelinks. Item {badge} used for site {site_id} is not allowed as a badge", "context": { "site_id": "{site_id}", "badge": "{badge}" } } |
| After applying a patch, badges field is not a list | 422 | {"code": "patched-sitelink-badges-format", "message": "Badges value for site {site_id} is not a list in patched sitelinks", "context": { "site_id": "{site_id}", "badges": "{badges}" } } |
Additional notes:
- How Action API handles it: https://www.wikidata.org/w/api.php?action=help&modules=wbsetsitelink / https://www.wikidata.org/w/api.php?action=help&modules=wbeditentity
Task breakdown:
- Add endpoint to OpenAPI spec (O)
- happy path (M)
- Handle edit metadata (bot flag, tags)
- feel free to use the request validation/deserialization but don't handle errors yet
- Generate the expected edit summary (J)
- Authorization (S)
- Validate user input (the patch document, item id, edit metadata) (D)
- Handle errors that occur while patching sitelinks (O)
- Validate the patched sitelinks (M)
- does not include sitelink conflict detection
- Handle patched sitelinks conflicts (J)
- Handle unexpected URL modification (url-not-modifiable) (S)
- should be included in the post patch validation
- validate and deserialize the sitelinks first and then compare the URLs in the (known to be valid!) patched serialization against the URLs in the original read model serialization
- Respond 404/409 if item not found or redirected (D)
- Use the usual middlewares (O)
- Add OpenAPI validation test (M)
- Mark PATCH sitelinks production ready (J)