Merge "REST: Add SetPropertyDescription to OAS"

wikimedia · Oct 9, 2023 · f008935 · f008935
2 parents 13878db + f78276d
commit f008935
Show file tree

Hide file tree

Showing 4 changed files with 66 additions and 39 deletions.
diff --git a/repo/rest-api/specs/global/requests.json b/repo/rest-api/specs/global/requests.json
@@ -50,7 +50,7 @@
 							"properties": {
 								"description": {
 									"type": "string",
-									"example": "English science fiction writer and humourist"
+									"example": "an example description"
 								}
 							},
 							"required": [ "description" ]

diff --git a/repo/rest-api/specs/global/responses.json b/repo/rest-api/specs/global/responses.json
@@ -688,6 +688,32 @@
 			}
 		}
 	},
+	"InvalidSetPropertyDescriptionInput": {
+		"description": "The request cannot be processed",
+		"content": {
+			"application/json": {
+				"schema": { "$ref": "./response-parts.json#/ContextError" },
+				"examples": {
+					"invalid-property-id": { "$ref": "./examples.json#/InvalidPropertyIdExample" },
+					"invalid-language-code": { "$ref": "./examples.json#/InvalidLanguageCodeExample" },
+					"invalid-description": { "$ref": "./examples.json#/InvalidDescriptionExample" },
+					"description-empty": { "$ref": "./examples.json#/DescriptionEmptyExample" },
+					"description-too-long": { "$ref": "./examples.json#/DescriptionTooLongExample" },
+					"label-description-same-value": {
+						"$ref": "./examples.json#/LabelDescriptionSameValueExample"
+					},
+					"invalid-edit-tag": { "$ref": "./examples.json#/InvalidEditTagExample" },
+					"comment-too-long": { "$ref": "./examples.json#/CommentTooLongExample" }
+				}
+			}
+		},
+		"headers": {
+			"Content-Language": {
+				"schema": { "type": "string" },
+				"description": "Language code of the language in which error message is provided"
+			}
+		}
+	},
 	"InvalidItemTermByLanguageInput": {
 		"description": "The request cannot be processed",
 		"content": {
@@ -1107,37 +1133,6 @@
 			}
 		}
 	},
-	"ItemDescription": {
-		"description": "Item's description in a specific language",
-		"headers": {
-			"Last-Modified": {
-				"schema": {
-					"type": "string"
-				},
-				"description": "Last modified date"
-			},
-			"ETag": {
-				"schema": {
-					"type": "string"
-				},
-				"description": "Last entity revision number"
-			},
-			"X-Authenticated-User": {
-				"schema": {
-					"type": "string"
-				},
-				"description": "Optional username of the user making the request"
-			}
-		},
-		"content": {
-			"application/json": {
-				"schema": {
-					"type": "string",
-					"example": "English science fiction writer and humourist"
-				}
-			}
-		}
-	},
 	"ItemAliases": {
 		"description": "Item's aliases by language",
 		"headers": {
@@ -1324,8 +1319,8 @@
 			}
 		}
 	},
-	"PropertyDescription": {
-		"description": "Property's description in a specific language",
+	"Description": {
+		"description": "A description in a specific language",
 		"headers": {
 			"Last-Modified": {
 				"schema": {
@@ -1350,7 +1345,7 @@
 			"application/json": {
 				"schema": {
 					"type": "string",
-					"example": "some property's description"
+					"example": "an example description"
 				}
 			}
 		}

diff --git a/repo/rest-api/specs/resources/descriptions/description-in-language-for-item.json b/repo/rest-api/specs/resources/descriptions/description-in-language-for-item.json
@@ -13,7 +13,7 @@
 			{ "$ref": "../../global/parameters.json#/Authorization" }
 		],
 		"responses": {
-			"200": { "$ref": "../../global/responses.json#/ItemDescription" },
+			"200": { "$ref": "../../global/responses.json#/Description" },
 			"304": { "$ref": "../../global/responses.json#/NotModified" },
 			"308": { "$ref": "../../global/responses.json#/Moved" },
 			"400": { "$ref": "../../global/responses.json#/InvalidItemTermByLanguageInput" },
@@ -38,11 +38,11 @@
 		"requestBody": { "$ref": "../../global/requests.json#/Description" },
 		"responses": {
 			"200": {
-				"$ref": "../../global/responses.json#/ItemDescription",
+				"$ref": "../../global/responses.json#/Description",
 				"description": "The updated Description in a specific language"
 			},
 			"201": {
-				"$ref": "../../global/responses.json#/ItemDescription",
+				"$ref": "../../global/responses.json#/Description",
 				"description": "The newly added Description in a specific language"
 			},
 			"304": { "$ref": "../../global/responses.json#/NotModified" },

diff --git a/repo/rest-api/specs/resources/descriptions/description-in-language-for-property.json b/repo/rest-api/specs/resources/descriptions/description-in-language-for-property.json
@@ -13,12 +13,44 @@
 			{ "$ref": "../../global/parameters.json#/Authorization" }
 		],
 		"responses": {
-			"200": { "$ref": "../../global/responses.json#/PropertyDescription" },
+			"200": { "$ref": "../../global/responses.json#/Description" },
 			"304": { "$ref": "../../global/responses.json#/NotModified" },
 			"400": { "$ref": "../../global/responses.json#/InvalidPropertyTermByLanguageInput" },
 			"404": { "$ref": "../../global/responses.json#/PropertyDescriptionNotFound" },
 			"412": { "$ref": "../../global/responses.json#/PreconditionFailedError" },
 			"500": { "$ref": "../../global/responses.json#/UnexpectedError" }
 		}
+	},
+	"put": {
+		"operationId": "replacePropertyDescription",
+		"tags": [ "descriptions" ],
+		"summary": "[WIP] Add / Replace a Property's description in a specific language",
+		"description": "This endpoint is currently in development and is not recommended for production use.",
+		"parameters": [
+			{ "$ref": "../../global/parameters.json#/PropertyId" },
+			{ "$ref": "../../global/parameters.json#/LanguageCode" },
+			{ "$ref": "../../global/parameters.json#/IfNoneMatch" },
+			{ "$ref": "../../global/parameters.json#/IfModifiedSince" },
+			{ "$ref": "../../global/parameters.json#/IfMatch" },
+			{ "$ref": "../../global/parameters.json#/IfUnmodifiedSince" },
+			{ "$ref": "../../global/parameters.json#/Authorization" }
+		],
+		"requestBody": { "$ref": "../../global/requests.json#/Description" },
+		"responses": {
+			"200": {
+				"$ref": "../../global/responses.json#/Description",
+				"description": "The updated Description in a specific language"
+			},
+			"201": {
+				"$ref": "../../global/responses.json#/Description",
+				"description": "The newly added Description in a specific language"
+			},
+			"304": { "$ref": "../../global/responses.json#/NotModified" },
+			"400": { "$ref": "../../global/responses.json#/InvalidSetPropertyDescriptionInput" },
+			"404": { "$ref": "../../global/responses.json#/PropertyNotFound" },
+			"412": { "$ref": "../../global/responses.json#/PreconditionFailedError" },
+			"415": { "$ref": "../../global/responses.json#/InvalidMediaType" },
+			"500": { "$ref": "../../global/responses.json#/UnexpectedError" }
+		}
 	}
 }