As a tool developer I want to be able to replace the statement data with new structure so that the tool can store non trivial edits
PUT /entities/items/{item_id}/statements/{statement_id}
PUT /statements/{statement_id}
Meant to be as a counterpart of PATCH "endpoint" (T306934), allowing to replace the whole statement structure with new data, e.g. when the client cannot or does not want to calculate the diff/patch. This will only replace existing statements and will not create a new statement if the given statement ID does not exist.
The format of the statement in the request body is the same as for the POST body. The ID will be ignored.
Responses:
- On the successful replacement of the statement content, API would respond with 200 and response body contains the statement data. Successful response should include ETag and Last-Modified headers with the relevant values
- 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 the request contains id in the statement data, the API should respond with 400 (error code: invalid-operation-change-statement-id, error message: Cannot change the ID of the existing statement) unless the provided ID matches the the statement's ID in the request's path
- If the request contains property in the statement data, 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
Other remarks:
- If statement data in the request contains 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
Authenticating user and checking their permission to make a change (including on a protected item) are out of scope of this story, and will be addressed separately.
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 (no automated edit summary part). Use the consistent empty "default" comment value if none provided.
- 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
For some inspiration might also see https://wmde.github.io/wikibase-rest-api-proposal/#/statements/put_statements__statement_id_ (non binding reference)
Note: The Statement ID should stay the same. The order of statements in the statement group should stay the same.