From d70eeac6614ab4f8629ec5f55e532ed687ff9bfd Mon Sep 17 00:00:00 2001 From: Jos Poortvliet Date: Mon, 20 Apr 2020 08:38:56 +0200 Subject: [PATCH] Create comments.rst --- .../client_apis/WebDAV/comments.rst | 95 +++++++++++++++++++ 1 file changed, 95 insertions(+) create mode 100644 developer_manual/client_apis/WebDAV/comments.rst diff --git a/developer_manual/client_apis/WebDAV/comments.rst b/developer_manual/client_apis/WebDAV/comments.rst new file mode 100644 index 000000000..76bae303d --- /dev/null +++ b/developer_manual/client_apis/WebDAV/comments.rst @@ -0,0 +1,95 @@ +## Comments + +Comments have a PHP API within OCP and also via WebDAV. Basic documentation below. + + +### Endpoint + +The Comments resource has an endpoint: + +``` +remote.php/comments/$OBJECTTYPE/$OBJECTID [/$COMMENTID] +``` + +The `ObjectID` endpoint accepts: +* `POST` for creating a comment +* `PROPFIND` to list comments, and also the read mark. You need to specify +attributes in the request. +* `PROPPATCH` to update the read mark, property name: +{http://owncloud.org/ns}readMarker +* `REPORT` to search comments + +The `CommentID` endpoint accepts: +* `PROPPATCH` to update the comment +* `DELETE` to delete it +* `PROPFIND` to list all properties + +For a list of properties, see: +`https://github.com/nextcloud/server/blob/master/apps/dav/lib/Comments/CommentNode.php#L108` + +### Examples of usage + +REPORT request: + +``` +curl -u user:pwd -i --data-binary "@report.xml" -X REPORT -H "Content-Type: text/xml" http://test.nextcloud.bla/master/remote.php/dav/comments/files/2156 +``` + +report.xml your receive: + +``` + + + 5 + 0 + 2016-01-18 22:10:30 + +``` + +Example Output (without headers): + +``` + + + + + 3 + 0 + 0 + 0 + first + comment + users + master + files + 2156 + 2016-01-18 22:01:16 + 2016-01-20 14:01:24 + + + + + 2 + 0 + 0 + 0 + first + comment + users + master + files + 2156 + 2016-01-18 22:01:12 + 2016-01-20 14:01:24 + + + +``` + +If you want a real life example of use, the announcement center has comments implemented. +See the comments related files in `https://github.com/nextcloud/announcementcenter/tree/master/js` +for frontend matters. Backendwise `OCP\Comments\ICommentsManager` is mostly close for housekeeping. +It was introduced in https://github.com/nextcloud/announcementcenter/pull/12, but +there are also some follow up PRs. + +