Document how to get/set/delete the topic of a change via REST
Change-Id: I07cc4148d822a964150a87354c8de4def2884601
Signed-off-by: Edwin Kempin <edwin.kempin@sap.com>
diff --git a/Documentation/rest-api-changes.txt b/Documentation/rest-api-changes.txt
index ebfaf56..19e5bde 100644
--- a/Documentation/rest-api-changes.txt
+++ b/Documentation/rest-api-changes.txt
@@ -465,6 +465,82 @@
}
----
+[[get-topic]]
+GET /changes/\{change-id\}/topic (Get Topic)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Retrieves the topic of a change.
+
+.Request
+----
+ GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/topic HTTP/1.0
+----
+
+.Response
+----
+ HTTP/1.1 200 OK
+ Content-Disposition: attachment
+ Content-Type: application/json;charset=UTF-8
+
+ )]}'
+ "Documentation"
+----
+
+If the change does not have a topic an empty string is returned.
+
+[[set-topic]]
+PUT /changes/\{change-id\}/topic (Set Topic)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Sets the topic of a change.
+
+The new topic must be provided in the request body inside a
+link:#topic-input[TopicInput] entity.
+
+.Request
+----
+ PUT /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/topic HTTP/1.0
+ Content-Type: application/json;charset=UTF-8
+
+ {
+ "topic": "Documentation"
+ }
+----
+
+As response the new topic is returned.
+
+.Response
+----
+ HTTP/1.1 200 OK
+ Content-Disposition: attachment
+ Content-Type: application/json;charset=UTF-8
+
+ )]}'
+ "Documentation"
+----
+
+If the topic was deleted the response is "`204 No Content`".
+
+[[delete-topic]]
+DELETE /changes/\{change-id\}/topic (Delete Topic)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Deletes the topic of a change.
+
+The request body does not need to include a link:#topic-input[
+TopicInput] entity if no review comment is added.
+
+Please note that some proxies prohibit request bodies for DELETE
+requests. In this case, if you want to specify a commit message, use
+link:#set-topic[PUT] to delete the topic.
+
+.Request
+----
+ DELETE /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/topic HTTP/1.0
+----
+
+.Response
+----
+ HTTP/1.1 204 No Content
+----
+
[[ids]]
IDs
@@ -720,6 +796,21 @@
link:#file-info[FileInfo] entities.
|===========================
+[[topic-input]]
+TopicInput
+~~~~~~~~~~
+The `TopicInput` entity contains information for setting a topic.
+
+[options="header",width="50%",cols="1,^1,5"]
+|===========================
+|Field Name ||Description
+|`topic` |optional|The topic. +
+The topic will be deleted if not set.
+|`message` |optional|
+Message to be added as review comment to the change when setting the
+topic.
+|===========================
+
GERRIT
------
