As a tool developer I want to change elements on the statement so that my tool can improve data in Wikibase instance.
As a gadget developer I want to change parts of the statement so that users of the gadget can correct mistakes on Wikidata

PATCH /entities/items/{item_id}/statements/{statement_id}
PATCH /statements/{statement_id}

See also:

• https://wmde.github.io/wikibase-rest-api-proposal/#/statements/patch_statements__statement_id_
• https://github.com/wmde/wikibase-rest-api-proposal/blob/master/DECISION-RESEARCH.md#updating-resources

Success case:

• status code 200 and the new statement state
• ETag header with the last revision ID
• Last-Modified header

Error cases:

• If the statement with the request ID does not exist, API would respond with 404 (error code and message as in POST responses)
• If the subject item of the statement is a redirect, API would also respond with 404 (error code and message as in POST responses)
• If applying the requested patch results in a change to the Statement ID, the API should respond with 400 (error code: invalid-operation-change-statement-id, error message: Cannot change the ID of the existing statement)
• If applying the requested patch results in a change to the mainsnak.property field, the API should respond with 400 (error code: invalid-operation-change-property-of-statement, error message: Cannot change the property of the existing statement) unless the provided property ID matches the the existing statement's property
• if the provided JSON Patch input is invalid (e.g. not a valid JSON, uses unrecognized operation names) the API should respond with 400 (error code invalid-patch, error message: The provided patch is invalid)
• if the provided patch cannot be applied to the given statement (e.g. paths referred do not exist on a given statement) the API should respond with 409 (error code cannot-apply-patch, error message The provided patch cannot be applied to the statement {statement_id})
  • if a test operation defined in the provided patch fails the API should respond with 409 (error code patch-test-failed, error message Test operation in the patch provided failed)
• if applying the provided patch results in an invalid statement (i.e. a statement that cannot be persisted, e.g. changes the value to an incorrect type not matching the property data type any more) the API should respond with 422 (error code: patched-statement-invalid, error message: The patch results in an invalid statement which cannot be stored)

Other remarks:

• If applying the requested patch results in fields that are not "valid" parts of the statement data, or are not expected to be specified by the client (except guid and property, see above) those are to be silently ignored, i.e. they are not stored by the API, and the API does not respond with error response to such requests

All editing REST API endpoints are meant to include a consistent "metadata" optional parameters

• mediawiki "metadata" can be specified:
  • "comment" to be included in the edit summary (excluding the "automatic summary" part for now)
  • mediawiki tag(s) for the edit
  • flag edit as made by a bot
• to help Wikibase solve potential edit conflict ("lost update problem"), the latest revision of an item known by a client when making the request can also be provided using If-Match HTTP header. In case the ETag provided is not the most recent version if the item, the API would response in 412 Precondition Failed response code.
  • As a timestamp-based counterpart, also use If-Unmodified-Since header with a respective logic.
  • 412 response should not include any extra text in response body. The response should also not include ETag and Last-Modified header