nextcloud
/
bookmarks
mirror of https://github.com/nextcloud/bookmarks
0
0
Fork 0
Code Issues Releases Wiki Activity

fix(docs): Update and fix lots of endpoints 

Signed-off-by: Marcel Klehr <mklehr@gmx.net>
This commit is contained in:
Marcel Klehr 2023-05-18 14:24:03 +02:00
parent 6fdd4adc7a
commit 94038836d2
4 changed files with 190 additions and 71 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

88
docs/bookmark.rst
View File

@ -4,6 +4,8 @@ Bookmarks
.. contents::
.. _bookmark:
Bookmark model
==============
@ -15,8 +17,26 @@ A bookmark has at least the following properties
:param string url: The Uniform Resource Locator that this bookmark represents
:param string title: A short humanly readable label for the bookmark
:param string description: A longer description or note on the bookmark
:param int added: The UNIX timestamp when this bookmark was created
:param string userId: The user ID of the nextcloud account that owns this bookmark
:param array tags: A list of tags this bookmark is tagged with
:param array folders: The folders this bookmark has been added to
:param int clickcount: The number of times this bookmark was opened
:param bool available: A boolean indicating whether the app could reach the bookmarked URL
.. versionadded:: 3.4.0
:param string|null htmlContent: The html content of the bookmarked web page
.. versionadded:: 4.2.0
:param string|null textContent: The html content of the bookmarked web page
.. versionadded:: 4.2.0
:param int|null archivedFile: The nextcloud file id, if this bookmark links to a non-HTML, non-plaintext file
.. versionadded:: 3.4.0
Query bookmarks
@ -36,8 +56,24 @@ Query bookmarks
:query conjunction: Set to ``and`` to require all search terms to be present, ``or`` if one should suffice. Default: ``or``
:query folder: Only return bookmarks that are direct children of the folder with the passed ID. The root folder has id ``-1``.
:query url: Only return bookmarks with this URL. With this parameter you can test whether a URL exists in the user's bookmarks.
.. versionadded:: 1.0.0
:query unavailable: Only return bookmarks that are dead links, i.e. return 404 status codes or similar.
:query archive: Only return bookmarks that whose contents have been archived.
.. versionadded:: 3.4.0
:query archived: Only return bookmarks that whose contents have been archived.
.. versionadded:: 3.4.0
:query untagged: Only return bookmarks that have no tags set
.. versionadded:: 0.12.0
:query duplicated: Only return bookmarks that are in multiple folders
.. versionadded:: 10.2.0
:>json string status: ``success`` or ``error``
:>json array data: The list of resulting bookmarks
@ -73,11 +109,11 @@ Create a bookmark
.. versionadded:: 0.11.0
:param id: the url of the new bookmark
:param array tags: Array of tags for this bookmark (these needn't exist and are created on-the-fly; this used to be `item[tags][]`, which is now deprecated)
:param string title: the title of the bookmark. If absent the title of the html site referenced by `url` is used
:param string description: A description for this bookmark
:param array folders: An array of IDs of the folders this bookmark should reside in.
:param url: the url of the new bookmark
:param array tags: Array of tags for this bookmark (these needn't exist and are created on-the-fly) (optional)
:param string title: the title of the bookmark. (optional; If absent the title of the html site referenced by `url` is used)
:param string description: A description for this bookmark (optional)
:param array folders: An array of IDs of the folders this bookmark should reside in. (optional; if absent the new bookmark will be put in the root folder)
:>json string status: ``success`` or ``error``
:>json object item: The created bookmark
@ -165,11 +201,11 @@ Edit a bookmark
.. versionadded:: 0.11.0
:param id: the url of the new bookmark
:param array tags: Array of tags for this bookmark (these needn't exist and are created on-the-fly; this used to be `item[tags][]`, which is now deprecated)
:param string title: the title of the bookmark. If absent the title of the html site referenced by `url` is used
:param string description: A description for this bookmark
:param array folders: An array of IDs of the folders this bookmark should reside in.
:param url: the url of the new bookmark (optional; if absent will not be changed)
:param array tags: Array of tags for this bookmark (these needn't exist and are created on-the-fly). (optional; if absent, will not be changed)
:param string title: the title of the bookmark. (optional; if absent, will not be changed)
:param string description: A description for this bookmark (optional; if absent, will not be changed)
:param array folders: An array of IDs of the folders this bookmark should reside in, the bookmark will be removed from all other folders it may have resided in (optional; if absent, will not be changed)
:>json string status: ``success`` or ``error``
:>json object item: The new bookmark after editing
@ -209,7 +245,7 @@ Delete a bookmark
.. delete:: /public/rest/v2/bookmark/(int:id)
:synopsis: Delete a bookmark
:synopsis: Delete a bookmark. Note: Often you only want to remove a bookmark from a folder, not delete it from all folders. There is a different endpoint for the former.
.. versionadded:: 0.11.0
@ -314,3 +350,31 @@ Export all bookmarks
<html>
...
Register that a bookmark was opened
==================================
.. post:: /public/rest/v2/bookmark/click
:synopsis: Delete a bookmark. Note: Often you only want to remove a bookmark from a folder, not delete it from all folders. There is a different endpoint for the former.
:query string url: The URL of the bookmark
**Example:**
.. sourcecode:: http
POST /index.php/apps/bookmarks/public/rest/v2/bookmark/click?url=https://nextcloud.com/ HTTP/1.1
Host: example.com
Accept: application/json
**Response:**
.. sourcecode:: http
HTTP/1.1 200 OK
Content-Type: application/json
{
"status": "success"
}

2
docs/conf.py
View File

@ -59,7 +59,7 @@ master_doc = 'index'
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
language = None
language = 'en'
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.

112
docs/folder.rst
View File

@ -12,14 +12,18 @@ Folder model
:param int id: The folder's unique id
:param string title: The humanly-readable label for the folder
:param int parent_folder: The folder's parent folder
:param string userId: The user ID of the nextcloud account that owns this folder
:param string userDisplayName: The name of the nextcloud account that owns this folder
.. versionadded:: 12.1.0
.. note::
The root folder has the magic id ``-1``, which is the same for every user.
Get full hierarchy
==================
Get full folder hierarchy
=========================
.. get:: /public/rest/v2/folder
@ -109,8 +113,8 @@ Create a folder
.. versionadded:: 0.15.0
:<json string title: The title of the new folder
:<json int parent_folder: The id of the parent folder for the new folder
:<json string title: The title of the new folder, defaults to ""
:<json int parent_folder: The id of the parent folder for the new folder, defaults to -1
:>json string status: ``success`` or ``error``
:>json object item: The new folder
@ -351,11 +355,14 @@ Get folder's content order
.. versionadded:: 0.15.0
:query int layers: The number of tree layers to return, defaults to 0 which returns only the immediate children
:>json string status: ``success`` or ``error``
:>json array data: An ordered list of child items
:>jsonarr string type: Either ``folder`` or ``bookmark``
:>jsonarr string id: The id of the bookmark or folder
:>jsonarr array children: In case more than one layers are returned, folders will have a this additional property with an array containing more items (or none)
**Example:**
@ -382,6 +389,37 @@ Get folder's content order
]
}
**Example:**
.. sourcecode:: http
GET /index.php/apps/bookmarks/public/rest/v2/folder/5/childorder?layers=1 HTTP/1.1
Host: example.com
Accept: application/json
**Response:**
.. sourcecode:: http
HTTP/1.1 200 OK
Content-Type: application/json
{
"status": "success",
"data": [
{"type": "folder", "id": 17, "children": [
{"type": "bookmark", "id": 234},
{"type": "bookmark", "id": 492},
{"type": "bookmark", "id": 250},
{"type": "folder", "id": 18 }
]
},
{"type": "bookmark", "id": 204},
{"type": "bookmark", "id": 192},
{"type": "bookmark", "id": 210}
]
}
Set folder's content order
==========================
@ -436,7 +474,7 @@ Get folder's contents
.. versionadded:: 3.0.0
:query int layers: How many layers of descendants to return at max. By default only immediate children are returned.
:query int layers: How many layers of descendants to return at max. Defaults to 0, retuning only immediate children.
:>json string status: ``success`` or ``error``
:>json array data: An ordered list of child items
@ -446,15 +484,12 @@ Get folder's contents
If the type of the item is ``folder``
:>jsonarr int id: The id of the folder
:>jsonarr string title: The title of the folder
:>jsonarr string userId: The owner of the folder
:>jsonarr array children: The children of the folder. This is only set, when the number of layers to return includes this folder.
If the type of the item is ``bookmark``
:>jsonarr string url: The URL of the bookmark
:>jsonarr string title: The title of the bookmark
:>jsonarr string description: Description of the bookmark
If the type of the item is ``bookmark`` it will have all properties of the Bookmark type (see :ref:`bookmark`).
**Example:**
@ -481,7 +516,7 @@ Get folder's contents
}
Get folder's contents
Get folder's content count
=====================
.. get:: /public/rest/v2/folder/(int:folder_id)/count
@ -518,7 +553,7 @@ Get public token
.. get:: /public/rest/v2/folder/(int:folder_id)/publictoken
:synopsis: Retrieve the public token of a folder that has been shared via a public link
:synopsis: Retrieve the public token of a folder that has been shared via a public link. This will return a 404 if the folder has no public token yet.
.. versionadded:: 3.0.0
@ -547,7 +582,7 @@ Get public token
"item": "dk3J8Qm"
}
Get public token
Create public token
================
.. post:: /public/rest/v2/folder/(int:folder_id)/publictoken
@ -608,3 +643,54 @@ Delete public token
{
"status": "success",
}
Import bookmarks into folder
============================
.. post:: /public/rest/v2/folder/(int:folder_id)/import
:synopsis: Import an HTML bookmarks file into a folder. Returns the newly created items.
.. versionadded:: 1.1.0
:formparam bm_import: The HTML file to be uploaded
**Example:**
.. sourcecode:: http
POST /index.php/apps/bookmarks/public/rest/v2/folder/-1/import HTTP/1.1
Host: example.com
Content-Length: 5038
Content-Type: multipart/form-data; boundary=------------------------8c1687317cdae5bf
--------------------------8c1687317cdae5bf
Content-Disposition: form-data; name="bm_import"; filename="bookmarks.html"
Content-Type: text/html
<html>
...
**Response:**
.. sourcecode:: http
HTTP/1.1 200 OK
Content-Type: application/json
{
"status": "success",
"data": [
{"type": "folder", "id": "17", "title": "foo", "children": [
{"type": "folder", "id": 18, "title": "bla", "children": [] }
{"type": "bookmark", "id": 234, "title": "Gnome", "url": "https://www.gnome.org"},
{"type": "bookmark", "id": 492, "title": "kernel", "url": "https://www.kernel.org"},
{"type": "bookmark", "id": 250, "title": "Test", "url": "https://www.test.de"},
{"type": "folder", "id": 18, "title": "foobar" "children": [] }
]
},
{"type": "bookmark", "id": "204", "title": "Nextcloud", "url": "https://nextcloud.com/"},
{"type": "bookmark", "id": "205", "title": "Google", "url": "https://google.com/"},
]
}

59
docs/share.rst
View File

@ -26,6 +26,11 @@ Create a share
.. versionadded:: 3.0.0
:<json string participant: the id of the sharee (mandatory)
:<json int type: the type of sharee (currently either ``1`` if it's a group, or ``0`` if it's a single user; mandatory)
:<json bool canWrite: Whether the participant has write access (optional; defaults to ``false``)
:<json bool canShare: Whether the sharee should be allowed to re-share the folder with others (optional; defaults to ``false``)
:>json string status: ``success`` or ``error``
:>json share item: The new share
@ -98,45 +103,10 @@ Get folder's shares
]
}
Get public token
================
.. get:: /public/rest/v2/folder/(int:folder_id)/publictoken
:synopsis: Retrieve the public token of a folder that has been shared via a public link
.. versionadded:: 3.0.0
:>json string status: ``success`` or ``error``
:>json share item: The public token
To use the token either make API requests with it (see :ref:`authentication`). Or point your browser to ``https://yournextcloud.com/index.php/apps/bookmarks/public/{token}``
**Example:**
.. sourcecode:: http
GET /index.php/apps/bookmarks/public/rest/v2/folder/5/publictoken HTTP/1.1
Host: example.com
Accept: application/json
**Response:**
.. sourcecode:: http
HTTP/1.1 200 OK
Content-Type: application/json
{
"status": "success",
"item": "dk3J8Qm"
}
Get share
=========
.. post:: /public/rest/v2/share/(int:share_id)
.. get:: /public/rest/v2/share/(int:share_id)
:synopsis: Get a share by id
@ -149,7 +119,7 @@ Get share
.. sourcecode:: http
POST /index.php/apps/bookmarks/public/rest/v2/share/17 HTTP/1.1
GET /index.php/apps/bookmarks/public/rest/v2/share/17 HTTP/1.1
Host: example.com
Accept: application/json
@ -162,8 +132,7 @@ Get share
{
"status": "success"
"data": [
{
"item": {
"id": 17,
"folderId": 201,
"participant": "friends",
@ -171,7 +140,6 @@ Get share
"canWrite": false,
"canShare": false
}
]
}
Edit share
@ -179,10 +147,13 @@ Edit share
.. put:: /public/rest/v2/share/(int:share_id)
:synopsis: Get a share by id
:synopsis: Edit a share
.. versionadded:: 3.0.0
:<json bool canWrite: Whether the sharee should be allowed to edit the shared contents (mandatory)
:<json bool canShare: Whether the sharee should be allowed to re-share the folder with others (mandatory)
:>json string status: ``success`` or ``error``
:>json share item: The requested share
@ -208,8 +179,7 @@ Edit share
{
"status": "success"
"data": [
{
"item": {
"id": 17,
"folderId": 201,
"participant": "friends",
@ -217,7 +187,6 @@ Edit share
"canWrite": true,
"canShare": false
}
]
}
Delete share
@ -235,7 +204,7 @@ Delete share
.. sourcecode:: http
POST /index.php/apps/bookmarks/public/rest/v2/share/17 HTTP/1.1
DELETE /index.php/apps/bookmarks/public/rest/v2/share/17 HTTP/1.1
Host: example.com
Accept: application/json