Page MenuHomePhabricator

๐Ÿท๏ธ๐Ÿ“œ Create or replace a label, or a description in a given language
Closed, ResolvedPublic13 Estimated Story Points

Description

PUT /entities/items/{item_id}/labels/{language_code}
PUT /entities/items/{item_id}/description/{language_code}

Request Payload (label)

{ 
  label: LABEL-TEXT
  (optional) comment: Edit comment
  (optional) tags: Edit tags (array/list)
  (optional) bot: true/false
}

Request Payload (description)

{ 
  description: DESCRIPTION-TEXT
  (optional) comment: Edit comment
  (optional) tags: Edit tags (array/list)
  (optional) bot: true/false
}

The respective successful responses should present the relevant data as a string -- similar to the responses of GET /entities/items/{item_id}/labels/{language_code}, and GET /entities/items/{item_id}/descriptions/{language_code} respectively.
If a label or a description in the given language didn't exist before the successful request the response should use 201 code. If the request changed the existing label or description, the response code should be 200.

The automated summaries for the edits made should be generated as described:

  • if the label in the given language is created (has not been defined before the API request): /* wbsetlabel-add:1|{language_code} */ LABEL-TEXT
  • if the label in the given language is replaced/updated (has been defined before the API request): /* wbsetlabel-set:1|{language_code} */ LABEL-TEXT
  • if the description in the given language is created (has not been defined before the API request): /* wbsetdescription-add:1|{language_code} */ DESCRIPTION-TEXT
  • if the description in the given language is replaced/updated (has been defined before the API request): /* wbsetdescription-set:1|{language_code} */ DESCRIPTION-TEXT

Error cases to consider:

  • if {item_id} does not exist, the API should generate a 404 response { "code": "item-not-found", "message": "Could not find an item with the ID: {item_id}" }
  • if {item_id} is not a valid item ID, the API should generate a 400 response { "code": "invalid-item-id", "message": "Not a valid item ID: {item_id}"}
  • if {language_code} is not a valid language code, the API should generate a 400 response { "code": "invalid-language-code", "message": "Not a valid language code: {language_code}"}
  • if {item_id} is a redirect, the API should generate a 409 response { "code": "redirected-item", "message": "Item {item_id} has been merged into {other_id}." }
  • if the provided label/description is invalid (in the sense of Wikibase label/description validation logic) the API should generated 400 response, containing, depending on the error
    • label/description empty
{
   "code": "label-empty",
   "message": "Label must not be empty",
}
  • label/description too long
{
   "code": "label-too-long",
   "message": "Label must be no more than {limit} characters long",
   "context": {
      "value": {label},
      "character-limit": {limit}
   }
}
    • if the edit results in creating a an item which has the exact same label and description in a given language, the edit should be prevent with error response: { "code": "label-description-same-value", "message": "Label and description for language code {language} can not have the same value.", "context": "language": {language} }
    • if the edit results in creating a an item which has the same label and description in a given language as an existing item, the edit should be prevented with error response: {"code":"item-label-description-duplicate", "message": "Item {dupe_id{ already has label "{label}" associated with language code {language}, using the same description text.}", "context": { "language": {language}, "label": {label}, "description": {description}. "matching-item-id": {dupe_item_id} }
    • other label or description validation error: { "code": "invalid-label, "message": "Not a valid label: {label-text}." }, or { "code": "invalid-description, "message": "Not a valid description: {description-text}." }
  • If an invalid Mediawiki edit tag is provided, the API should generate a 400 response { "code": "invalid-edit-tag", "message": "Invalid MediaWiki tag: {tag}"}
  • If a value for bot parameter other than true or falseis provided, Mediawiki REST API framework's error is to be used

Note:

  • mul is a valid language code for a label but it is not allowed for descriptions

Related Objects

StatusSubtypeAssignedTask
ResolvedIfrahkhanyaree_WMDE
ResolvedWMDE-leszek
ResolvedOllie.Shotton_WMDE
ResolvedJakob_WMDE
ResolvedJakob_WMDE
ResolvedJakob_WMDE
InvalidNone
ResolvedOllie.Shotton_WMDE
ResolvedJakob_WMDE
ResolvedSilvan_WMDE
ResolvedSilvan_WMDE
ResolvedOllie.Shotton_WMDE
ResolvedOllie.Shotton_WMDE
ResolvedOllie.Shotton_WMDE
ResolvedJakob_WMDE
ResolvedJakob_WMDE
ResolvedOllie.Shotton_WMDE
Resolvedโ€ข WMDE_Norman
ResolvedOllie.Shotton_WMDE
Resolvedโ€ข WMDE_Norman
ResolvedOllie.Shotton_WMDE
ResolvedOllie.Shotton_WMDE
ResolvedBUG REPORTSilvan_WMDE
ResolvedBUG REPORTOllie.Shotton_WMDE

Event Timeline

Notes from backlog refinement:

  • validation: we can think of "empty" and "too long" are there any other validation rules? -- if not: should the error message mention length or the limit?
  • sanitization: do we trim whitespaces etc? -- we should try it out and check what action API does
  • separate the two tasks? it may be managable in one sprint, but could just as well be broken into two stories for more flexibility
Silvan_WMDE set the point value for this task to 13.Feb 22 2023, 10:59 AM

Answers:

  • validation: empty and too long cases sound good for now.

Errors:
empty label/description

{
   "code": "label-empty",
   "message": "Label must not be empty",
}

(no context object - or empty object if preferred)

label/description too long: ('label' used as example)

{
   "code": "label-too-long",
   "message": "Label must be no more than {limit} characters long",
   "context": {
      "value": {label},
      "character-limit": {limit}
   }
}

There's existing i18n message in Wikibase used in Action API errors, wikibase-validator-label-too-long -- using the same message would be preferred

  • sanitization: Action API wbsetlabel does trim leading and trailing whitespace, so should do the same please
  • NOTE: wbsetlabel Action API seems to have a special behaviour baked in: sending an empty string as a label would remove (if present) the label in a given language. This behaviour should NOT be replicated in the Wikibase REST API. DELETE method is to be used explicitly for removal of an individual label/description

Task Breakdown notes:

  • PUT /entities/items/{item_id}/labels/{language_code}
Silvan_WMDE renamed this task from Create or replace a label, or a description in a given language to ๐Ÿท๏ธ Create or replace a label, or a description in a given language.Mar 29 2023, 1:32 PM
Silvan_WMDE renamed this task from ๐Ÿท๏ธ Create or replace a label, or a description in a given language to ๐Ÿท๏ธ๐Ÿ“œ Create or replace a label, or a description in a given language.

@WMDE-leszek When updating the OAS (T333644 and T333644), I assumed that 304 Not Modified, 412 Precondition Failed, and 415 Unsupported Media Type should also be part of this story. I also added the invalid-bot-flag to the 400 Bad Request response. Let us know if this is not the case. =)

I didn't find any specific recommendation about using (or not) Location header in 201 response if the URI of the created resource is the target PUT request URI, so I dare to interpret RFC as: no need to include Location header in 201 responses after creating a label/description as it would be redundant.

Check whether characters like tab, new line, vertical whitespace etc are allowed in labels/description when using Action API