Terms PUT Process
Term PUT Path (Setting Labels/Descriptions for Language)
[Entitybase PUT /entities/{type}/{id}/labels/{lang} or /descriptions/{lang} - entitybase/v1/*.py]
+--> Receive PUT Request with term data payload
| +--> For Labels: Extract "value" field from request
| +--> For Descriptions: Extract "description" field from Wikibase format
+--> Validate Clients: vitess and s3 initialized
+--> Check Entity Exists: vitess.entity_exists(entity_id) == True
+--> Check Not Deleted: vitess.is_entity_deleted(entity_id) == False
+--> Check Permissions: not archived/locked/mass_edit_protected
+--> Get Current Entity: EntityReadHandler.get_entity(entity_id, vitess, s3)
+--> Extract Term Type: labels or descriptions from URL path
+--> Validate Term Data: check required fields and format
+--> Update Entity Data: entity_data[term_type][language_code] = new_term_value
+--> Calculate New Revision ID: head_revision_id + 1
+--> Prepare Revision Data: copy entity_data, set edit_type="term_put"
+--> Hash Entity Content: MetadataExtractor.hash_entity(entity_data)
+--> Process Term Storage Updates:
| +--> For Labels: Update Vitess entity_terms table
| | +--> Hash new label: hash_string(new_label_value)
| | +--> Insert/update in entity_terms: INSERT ... ON DUPLICATE KEY
| | +--> Update revision labels_hashes: {language_code: new_hash}
| +--> For Descriptions: Update S3 metadata storage
| | +--> Hash new description: hash_string(new_description_value)
| | +--> Store in S3: s3.write_metadata("descriptions", hash, description_value)
| | +--> Update revision descriptions_hashes: {language_code: new_hash}
+--> Write Revision to S3: s3.write_revision(entity_id, new_revision_id, revision_data)
+--> Update Vitess Revision Table: vitess.create_revision(entity_id, new_revision_id, revision_data)
+--> Update Head Pointer: vitess.update_head_revision(entity_id, new_revision_id)
+--> Publish Change Event: stream_producer.publish_change(TERM_PUT event)
+--> Return EntityResponse with updated entity data
Term PUT Validation
[Entitybase PUT endpoint validation]
+--> Validate Entity ID: matches /^[A-Z]\d+$/
+--> Validate Language Code: matches /^[a-z-]+$/
+--> Validate Term Type: in ['labels', 'descriptions']
+--> Validate Request Body:
| +--> For Labels: {"value": "string"} (1-250 chars)
| +--> For Descriptions: {"description": "string", "tags": [...], "bot": bool, "comment": "string"} (1-500 chars)
+--> Check Entity State: not deleted, not locked/archived
+--> Check User Permissions: can modify entity
Wikibase API Redirect
[Wikibase PUT /entities/{type}/{id}/labels/{lang} or /descriptions/{lang} - wikibase/v1/*.py] +--> Receive Wikibase PUT request with full payload +--> Return 307 Redirect to: /entitybase/v1/entities/{type}/{id}/{term_type}/{lang} +--> Preserve request body and PUT method
Request Format Examples
Labels PUT
{
"value": "English mathematician and writer",
"tags": [],
"bot": false,
"comment": "set English label"
}
Descriptions PUT (Wikibase format)
{
"description": "the subject is a concrete object (instance) of this class, category, or object group",
"tags": [],
"bot": false,
"comment": "set English description"
}
Error Handling
+--> Entity Not Found: 404 Not Found
+--> Entity Deleted: 410 Gone
+--> Entity Locked/Archived: 409 Conflict
+--> Invalid Request Format: 400 Bad Request
+--> Term Value Too Long: 400 Bad Request
+--> Permission Denied: 403 Forbidden
+--> Storage Failure: 500 Internal Server Error
Key Differences from PATCH Operations
- Complete Replacement: PUT replaces entire term value vs PATCH partial modifications
- Simple Validation: Direct value validation vs JSON Patch operation validation
- Storage Updates: Full term replacement in storage vs selective updates
- Use Cases: | Operation | Labels/Descriptions | Aliases | |-----------|-------------------|---------| | Set/Replace | PUT /labels/{lang} | PATCH add/replace operations | | Partial Edit | N/A | PATCH operations | | Language Add | PUT (creates if missing) | PATCH add operations |
Performance Characteristics
- Read Operations: 1 entity read, 1 S3 revision fetch
- Write Operations: 1 S3 revision write, 1 Vitess term insert (for labels)
- Hash Calculations: Full entity re-hash + individual term hash
- Storage Impact: New term storage + updated revision metadata
Relationship to Other Term Operations
- GET: Retrieve term value
- PUT: Set/replace entire term value
- PATCH: Apply partial modifications (aliases only)
- DELETE: Remove term entirely
Note: Term PUT provides complete value replacement for labels and descriptions, following entity update patterns with selective term storage management and full revision history preservation.