As a tool builder I want to be able to change aliases of an item so that work in my tool can be saved back to Wikidata.
PATCH /entities/items/{item_id}/aliases
Acceptance criteria:
- 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 aliases data, using the similar structure as GET /entities/items/{item_id}/aliases.
- Handle HTTP conditional request headers as in PATCH /entities/items/{item_id}/labels
- Handle user authentication/authorization like in PATCH /entities/items/{item_id}/labels
- duplicate aliases are not allowed per language
- cross-language "collision detection" does not apply for aliases
- All edit data is validated
Autocomments:
- should mimic the wbeditentity behavior when editing aliases:
- If the change results in changing aliases in not more than 50 languages: /* wbeditentity-update-languages-short:0||LANGS */
- If the change results in changing aliases in 51 or more languages: /* wbeditentity-update-languages:0||LANG_COUNT */
- where LANGS is a comma separated list of alphabeticall-sorted language codes of relevant languages (e.g. de, en, es, fi, fr, it). LANG_COUNT is a number of languages with changed aliases
- the boundary number of 50 languages is defined in ChangedLanguagesCounter::SHORTENED_SUMMARY_MAX_EDIT constant (not configurable)
Error cases considered:
| error type | HTTP Response code | Response content |
|---|---|---|
| ID provided is not a valid item ID | 400 | "code": "invalid-item-id", "message": "Not a valid item ID: '{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" |
| 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> } |
| Item with the given ID does not exist | 404 | "code": "item-not-found", "message": "Could not find an item with the ID: '{item_id}'" |
| 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 changes an invalid language code is used | 422 | "code": "patched-aliases-invalid-language-code" "message": "Not a valid language code '{language_code}' in changed aliases" "context": { "language": <language_code> } |
| After changes an alias is invalid (empty, too long) | 422 | "code": "patched-alias-empty"/"patched-alias-too-long" "message": "Changed alias for '{lang_code}' cannot be empty" / "Changed alias for '{lang_code}' must not be more than {limit} characters long" "context": { "language": <language_code> "value": <alias> (too long alias case only) "character-limit": <limit> (too long alias case only) } |
| After changes alias/aliases are invalid. Three cases are as follows: 1) Entire value for aliases is invalid, 2) an alias in the list contains invalid character and 3) aliases haven't been added as a list | 422 | "code": "patched-aliases-invalid-field" "message": "Patched value for '{field}' is invalid" "context": { "path": <field>, "value": <value>} } |
| Duplicates in aliases not allowed | 422 | "code": "patched-duplicate-alias" "message": "Aliases in language '{language_code}' contain duplicate alias: '{alias}'" "context": { "alias": <alias> "language": <language_code> } |
Additional notes:
- How Action API handles it (somewhat): https://www.wikidata.org/w/api.php?action=help&modules=wbeditentity
Implementation steps:
- Add endpoint to OAS - 963994
- Implement happy path - 965090
- use the use case validator for deserialization only, but don't handle or test any errors it throws yet
- create an AliasesDeserializer
- don't generate and edit summary yet
- ETag and Last-Modified
- Generate the expected edit summary - 965713
- try to make TermsEditSummaryToFormattableSummaryConverter reusable for aliases
- Handle request validation errors - 966184
- Respond 404/409 if the item is not found or is a redirect - 966210
- Authorization - 966223
- Handle errors that occur while patching the aliases - 966506
- test condition, addressing fields that don't exist, ...
- Validate the patched aliases - 966260
- handles all cases where the patched JSON structure cannot be deserialized into a valid aliases AliasGroupList (empty alias, alias too long, alias containing invalid characters, duplicate aliases, language code)
- Use the usual middlewares and add the route handler to RouteHandlersTest - 966576
- Add OpenAPI validation test - 966577
- Mark as production ready