As a tool builder I want to be able to edit parts of aliases of a property so that the work in my tool can be saved back to Wikidata.
PATCH /entities/properties/{property_id}/aliases
**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 aliases data, using the similar structure as `GET /entities/properties/{property_id}/aliases`.
- Handle HTTP conditional request headers as in PATCH /entities/properties/{property_id}/aliases
- Handle user authentication/authorization like in PATCH /entities/properties/{property_id}/aliases
- 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:
<table>
<tr>
<th>error type</th>
<th> HTTP Response code</th>
<th>Response content</th>
</tr>
<tr>
<td>Property with the given ID does not exist</td>
<td>404</td>
<td>
`"code": "property-not-found",`
`"message": "Could not find a property with the ID: '{property_id}'"`
</td>
</tr>
<tr>
<td>ID provided is not a valid property ID</td>
<td>400</td>
<td>
` "code": "invalid-property-id",`
`"message": "Not a valid property ID: '{item_id}'"`
</td>
</tr>
<tr>
<td>Invalid JSON patch (general error)</td>
<td>400</td>
<td>
`"code": "invalid-patch"`
`"message": "The provided patch is invalid"`
</td>
</tr>
<tr>
<td>incorrect JSON patch operation</td>
<td>400</td>
<td>
`"code": "invalid-patch-operation"`
`"message": "Incorrect JSON patch operation: '<op>'"`
`"context": { "operation": <operation_object> }`
</td>
</tr>
<tr>
<td>
invalid field type in JSON patch
(either of `op`, `path`, `from` is not a string)
</td>
<td>400</td>
<td>
`"code": "invalid-patch-field-type"`
`"message": "The value of '<field>' must be of type string"`
`"context": { "operation": <operation_object>, "field": <field> }`
</td>
</tr>
<tr>
<td>
missing mandatory field in JSON patch
(`op`, `path`, `value`, also `from` on copy/move patches)
</td>
<td>400</td>
<td>
`"code": "missing-json-patch-field"`
`"message": "Missing '<field>' in JSON patch"`
`"context": { "operation": <operation_object>, "field": <field> }`
</td>
</tr>
<tr>
<td>Target of JSON Patch not found on the object</td>
<td>409</td>
<td>
`"code": "patch-target-not-found",`
`"message": "Target '<target>' not found on the resource",`
`"context": {`
` "operation": <operation_object>,`
` "field": <path>`
`}`
</td>
</tr>
<tr>
<td>JSON Patch test operation failed</td>
<td>409</td>
<td>
`"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>`
`}`
</td>
</tr>
<tr>
<td>After changes an invalid language code is used</td>
<td>422</td>
<td>
`"code": "patched-alias-invalid-language-code"`
`"message": "Not a valid language code '{language_code}' in changed aliases"`
`"context": {`
` "language": <language_code>`
`}`
</td>
</tr>
<tr>
<td>After changes an alias is invalid (empty, too long)</td>
<td>422</td>
<td>
`"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)
`}`
</td>
</tr>
<tr>
<td> After changes
the alias
list includes/aliases are invalid
values (e.g.
an alias containing invalid characterThree cases are as follows: 1) Entire value for aliases is invalid,
or2) an alias in the list contains invalid character and 3) aliases
arhaven't
been added as a list
)</td>
<td>422</td>
<td>
`"code": "patched-aliases-invalid
-field"`
`"message": "
Changed aliasesPatched value for '{
language_codefield}' is invalid
: '{alias}'/'{aliases}'"`"`
`"context": {
`
`"value "path": <
alias or aliases>`
`"languagfield>, "value": <
language_code>`value>}`
`}`
</td>
</tr>
<tr>
<td>Duplicates in aliases not allowed </td>
<td>422</td>
<td>
`"code": "patched-duplicate-alias"`
`"message": "Aliases in language {language_code} contain duplicate alias: '{alias}' "`
`"context": {`
`"value": <alias>`
`"language": <language_code>`
`}`
</td>
</tr>
<tr>
<td>Invalid edit tag</td>
<td>400</td>
<td>
`{ "code": "invalid-edit-tag", "message": "Invalid MediaWiki tag: {tag}" }`
</td>
</tr>
<tr>
<td>Comment too long</td>
<td>400</td>
<td>
`{"code": "comment-too-long", "message": "Comment must not be longer than {limit} characters"}`
</td>
</tr>
</table>
Additional notes:
* How Action API handles it (somewhat): https://www.wikidata.org/w/api.php?action=help&modules=wbeditentity
* REST API proposal: https://wmde.github.io/wikibase-rest-api-proposal/#/aliases/patch_entities__entity_type___entity_id__aliases
Implementation steps:
[x] add to OAS
[x] happy path
* 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
[x] generate the expected edit summary
* try to make `TermsEditSummaryToFormattableSummaryConverter` reusable for aliases
[x] Handle request validation errors
[x] Respond 404 if property not found
[x] Authorization
[x] Handle errors that occur while patching the aliases (test condition, addressing fields that don't exist, ...)
[x] Validate the patched aliases
* 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`
* Add OpenAPI validation test
* Mark as production ready