mirror of https://github.com/nextcloud/bookmarks
Update docs
This commit is contained in:
Marcel Klehr
parent
cbdcbf1af0
commit
9485a8a9d9
|
|
@ -20,7 +20,6 @@ Talk to us on [gitter](https://gitter.im/nextcloud-bookmarks/community) or in #n
|
|||
|
||||
PHP extensions:
|
||||
|
||||
- gmp: \*
|
||||
- intl: \*
|
||||
- mbstring: \*
|
||||
|
||||
|
|
|
|||
|
|
@ -1,5 +1,39 @@
|
|||
==============
|
||||
Authentication
|
||||
==============
|
||||
|
||||
|
||||
.. _authentication:
|
||||
|
||||
User-based authentication
|
||||
=========================
|
||||
|
||||
In order to access the REST API you will need to provide credentials for the user on behalf of which you'd
|
||||
like to access the bookmarks app. This should be done using Basic Auth and must happen for every request.
|
||||
|
||||
|
||||
.. sourcecode:: http
|
||||
|
||||
GET /index.php/apps/bookmarks/public/rest/v2/bookmark HTTP/1.1
|
||||
Host: example.com
|
||||
Accept: application/json
|
||||
Authorization: basic 345678ikmnbvcdewsdfgzuiolkmnbvfr==
|
||||
|
||||
Token-based authentication
|
||||
==========================
|
||||
If a user has shared one of their folders publicly, you can access its contents via the token as part of the public link.
|
||||
You may bass this token to the various endpoints using the ``token`` GET-parameter or by setting it as
|
||||
part of the ``Authorization header``.
|
||||
|
||||
.. sourcecode:: http
|
||||
|
||||
GET /index.php/apps/bookmarks/public/rest/v2/bookmark?token=j5KJr7c HTTP/1.1
|
||||
Host: example.com
|
||||
Accept: application/json
|
||||
|
||||
.. sourcecode:: http
|
||||
|
||||
GET /index.php/apps/bookmarks/public/rest/v2/bookmark HTTP/1.1
|
||||
Host: example.com
|
||||
Accept: application/json
|
||||
Authorization: bearer j5KJr7c
|
||||
|
|
|
|||
|
|
@ -28,12 +28,12 @@ Query bookmarks
|
|||
|
||||
.. versionadded:: 0.11.0
|
||||
|
||||
:query conjunction: Set to `and` to require all tags to be present, ``or`` if one should suffice. Default: ``or``
|
||||
:query conjunction: Set to ``and`` to require all tags to be present, ``or`` if one should suffice. Default: ``or``
|
||||
:query tags[]: An array of tags that bookmarks returned by the endpoint should have
|
||||
:query page: if this is non-negative, results will be paginated by 10 bookmarks a page. Default: ``0``
|
||||
:query page: if this is non-negative, results will be paginated by 10 bookmarks a page. Default: ``0``.
|
||||
:query sortby: The column to sort the results by; one of ``url``, ``title``, ``description``, ``public``, ``lastmodified``, ``clickcount``. Default: ``lastmodified``.
|
||||
:query search[]: An array of words to search for in the following columns `url`, `title`, `description`
|
||||
:query folder: Only return bookmarks that are direct children of the folder with the passed ID. The root folder has id `-1`.
|
||||
:query search[]: An array of words to search for in the following columns ``url``, ``title``, ``description``
|
||||
: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. This will only ever return just one bookmark or none, because the app doesn't store duplicates. Thus, with this parameter you can test whether a URL exists in the user's bookmarks. This parameter cannot be mixed with the others.
|
||||
|
||||
:>json string status: ``success`` or ``error``
|
||||
|
|
@ -229,3 +229,55 @@ Delete a bookmark
|
|||
{
|
||||
"status": "success"
|
||||
}
|
||||
|
||||
Get a preview image
|
||||
===================
|
||||
|
||||
.. get:: /public/rest/v2/bookmark/(int:id)/image
|
||||
|
||||
:synopsis: Retrieve the preview image of a bookmark
|
||||
|
||||
.. versionadded:: 1.0.0
|
||||
|
||||
**Example:**
|
||||
|
||||
.. sourcecode:: http
|
||||
|
||||
GET /index.php/apps/bookmarks/public/rest/v2/bookmark/7/image HTTP/1.1
|
||||
Host: example.com
|
||||
|
||||
|
||||
**Response:**
|
||||
|
||||
.. sourcecode:: http
|
||||
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: image/png
|
||||
|
||||
... binary data ...
|
||||
|
||||
Get a favicon
|
||||
=============
|
||||
|
||||
.. get:: /public/rest/v2/bookmark/(int:id)/favicon
|
||||
|
||||
:synopsis: Retrieve the favicon of a bookmark
|
||||
|
||||
.. versionadded:: 1.0.0
|
||||
|
||||
**Example:**
|
||||
|
||||
.. sourcecode:: http
|
||||
|
||||
GET /index.php/apps/bookmarks/public/rest/v2/bookmark/7/favicon HTTP/1.1
|
||||
Host: example.com
|
||||
|
||||
|
||||
**Response:**
|
||||
|
||||
.. sourcecode:: http
|
||||
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: image/png
|
||||
|
||||
... binary data ...
|
||||
|
|
|
|||
153
docs/folder.rst
153
docs/folder.rst
|
|
@ -19,7 +19,7 @@ Folder model
|
|||
|
||||
|
||||
Get full hierarchy
|
||||
=============
|
||||
==================
|
||||
|
||||
.. get:: /public/rest/v2/folder
|
||||
|
||||
|
|
@ -321,6 +321,8 @@ Remove bookmark from folder
|
|||
|
||||
:>json string status: ``success`` or ``error``
|
||||
|
||||
If this is the only folder this bookmark resides in, the bookmark will be deleted entirely.
|
||||
|
||||
**Example:**
|
||||
|
||||
.. sourcecode:: http
|
||||
|
|
@ -424,3 +426,152 @@ Set folder's content order
|
|||
{
|
||||
"status": "success"
|
||||
}
|
||||
|
||||
Get folder's contents
|
||||
=====================
|
||||
|
||||
.. get:: /public/rest/v2/folder/(int:folder_id)/children
|
||||
|
||||
:synopsis: Retrieve all of a folder's contents (with varying depth)
|
||||
|
||||
.. versionadded:: 3.0.0
|
||||
|
||||
:query int layers: How many layers of descendants to return at max. By default only immediate children are returned.
|
||||
|
||||
:>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
|
||||
|
||||
If the type of the item is ``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
|
||||
|
||||
**Example:**
|
||||
|
||||
.. sourcecode:: http
|
||||
|
||||
GET /index.php/apps/bookmarks/public/rest/v2/folder/5/children 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", "title": "foo", "userId": "admin"},
|
||||
{"type": "bookmark", "id": "204", "title": "Nextcloud", "url": "https://nextcloud.com/"},
|
||||
{"type": "bookmark", "id": "204", "title": "Google", "url": "https://google.com/"},
|
||||
]
|
||||
}
|
||||
|
||||
|
||||
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 string 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 public token
|
||||
================
|
||||
|
||||
.. post:: /public/rest/v2/folder/(int:folder_id)/publictoken
|
||||
|
||||
:synopsis: Create a public link for a folder
|
||||
|
||||
.. versionadded:: 3.0.0
|
||||
|
||||
:>json string status: ``success`` or ``error``
|
||||
:>json string item: The token that can be used to access the folder publicly.
|
||||
|
||||
**Example:**
|
||||
|
||||
.. sourcecode:: http
|
||||
|
||||
POST /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"
|
||||
}
|
||||
|
||||
Delete public token
|
||||
===================
|
||||
|
||||
.. delete:: /public/rest/v2/folder/(int:folder_id)/publictoken
|
||||
|
||||
:synopsis: Remove the public link for a folder
|
||||
|
||||
.. versionadded:: 3.0.0
|
||||
|
||||
:>json string status: ``success`` or ``error``
|
||||
|
||||
**Example:**
|
||||
|
||||
.. sourcecode:: http
|
||||
|
||||
POST /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",
|
||||
}
|
||||
|
|
|
|||
|
|
@ -1,9 +1,9 @@
|
|||
Welcome to the docs for the Nextcloud Bookmarks API!
|
||||
====================================================
|
||||
Nextcloud Bookmarks API
|
||||
=======================
|
||||
|
||||
The Nextcloud Bookmarks app provides you with a web interface for collecting and organizing bookmarks to the sites on the web that are precious to you. You can browse and filter your bookmarks via tags and folders and by using the built-in search feature. Furthermore, in order to access your bookmarks anywhere, it also allows you to synchronize third-party clients via a built-in REST API.
|
||||
The Nextcloud Bookmarks app provides you with a web interface for collecting, organizing and sharing bookmarks to the sites on the web that are precious to you. You can browse and filter your bookmarks via tags, folders and by using the built-in search feature and you can share folders with users and groups and using public links. Furthermore, in order to access your bookmarks anywhere, it also allows you to synchronize third-party clients via a built-in REST API.
|
||||
|
||||
These docs describe how to use this API.
|
||||
This documentation describes how to use this API.
|
||||
|
||||
.. toctree::
|
||||
:caption: Contents:
|
||||
|
|
@ -12,3 +12,4 @@ These docs describe how to use this API.
|
|||
bookmark
|
||||
tag
|
||||
folder
|
||||
share
|
||||
|
|
|
|||
|
|
@ -0,0 +1,251 @@
|
|||
=======
|
||||
Shares
|
||||
=======
|
||||
|
||||
.. contents::
|
||||
|
||||
Share model
|
||||
============
|
||||
|
||||
.. object:: Share
|
||||
|
||||
:param int id: The share's unique id
|
||||
:param int folderId: The id of the folder that was shared
|
||||
:param string participant: The id of the participant that the folder was shared to
|
||||
:param int type: The participant type. Currently either ``0`` for users, or ``1`` for groups.
|
||||
:param boolean canWrite: Whether the participant has write access.
|
||||
:param boolean canShare: Whether the participant is allowed to reshare the folder or subfolders to other users, including the creation of public links.
|
||||
|
||||
|
||||
Create a share
|
||||
==============
|
||||
|
||||
.. post:: /public/rest/v2/folder/(int:folder_id)/shares
|
||||
|
||||
:synopsis: Create a share for a folder
|
||||
|
||||
.. versionadded:: 3.0.0
|
||||
|
||||
:>json string status: ``success`` or ``error``
|
||||
:>json share item: The new share
|
||||
|
||||
**Example:**
|
||||
|
||||
.. sourcecode:: http
|
||||
|
||||
POST /index.php/apps/bookmarks/public/rest/v2/folder/5/shares HTTP/1.1
|
||||
Host: example.com
|
||||
Accept: application/json
|
||||
|
||||
**Response:**
|
||||
|
||||
.. sourcecode:: http
|
||||
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"status": "success"
|
||||
"item": {
|
||||
"id": 5,
|
||||
"folderId": 201,
|
||||
"participant": "friends",
|
||||
"type": 1,
|
||||
"canWrite": false,
|
||||
"canShare": false
|
||||
}
|
||||
}
|
||||
|
||||
Get folder's shares
|
||||
===================
|
||||
|
||||
.. get:: /public/rest/v2/folder/(int:folder_id)/shares
|
||||
|
||||
:synopsis: Retrieves all shares of a folder
|
||||
|
||||
.. versionadded:: 3.0.0
|
||||
|
||||
:>json string status: ``success`` or ``error``
|
||||
:>json array data: The shares of this folder
|
||||
|
||||
|
||||
**Example:**
|
||||
|
||||
.. sourcecode:: http
|
||||
|
||||
GET /index.php/apps/bookmarks/public/rest/v2/folder/5/shares HTTP/1.1
|
||||
Host: example.com
|
||||
Accept: application/json
|
||||
|
||||
**Response:**
|
||||
|
||||
.. sourcecode:: http
|
||||
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"status": "success"
|
||||
"data": [
|
||||
{
|
||||
"id": 5,
|
||||
"folderId": 201,
|
||||
"participant": "friends",
|
||||
"type": 1,
|
||||
"canWrite": false,
|
||||
"canShare": false
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
|
||||
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)
|
||||
|
||||
:synopsis: Get a share by id
|
||||
|
||||
.. versionadded:: 3.0.0
|
||||
|
||||
:>json string status: ``success`` or ``error``
|
||||
:>json share item: The requested share
|
||||
|
||||
**Example:**
|
||||
|
||||
.. sourcecode:: http
|
||||
|
||||
POST /index.php/apps/bookmarks/public/rest/v2/share/17 HTTP/1.1
|
||||
Host: example.com
|
||||
Accept: application/json
|
||||
|
||||
**Response:**
|
||||
|
||||
.. sourcecode:: http
|
||||
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"status": "success"
|
||||
"data": [
|
||||
{
|
||||
"id": 17,
|
||||
"folderId": 201,
|
||||
"participant": "friends",
|
||||
"type": 1,
|
||||
"canWrite": false,
|
||||
"canShare": false
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
Edit share
|
||||
==========
|
||||
|
||||
.. put:: /public/rest/v2/share/(int:share_id)
|
||||
|
||||
:synopsis: Get a share by id
|
||||
|
||||
.. versionadded:: 3.0.0
|
||||
|
||||
:>json string status: ``success`` or ``error``
|
||||
:>json share item: The requested share
|
||||
|
||||
**Example:**
|
||||
|
||||
.. sourcecode:: http
|
||||
|
||||
PUT /index.php/apps/bookmarks/public/rest/v2/share/17 HTTP/1.1
|
||||
Host: example.com
|
||||
Accept: application/json
|
||||
|
||||
{
|
||||
"canWrite": true,
|
||||
"canShare": false
|
||||
}
|
||||
|
||||
**Response:**
|
||||
|
||||
.. sourcecode:: http
|
||||
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"status": "success"
|
||||
"data": [
|
||||
{
|
||||
"id": 17,
|
||||
"folderId": 201,
|
||||
"participant": "friends",
|
||||
"type": 1,
|
||||
"canWrite": true,
|
||||
"canShare": false
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
Delete share
|
||||
============
|
||||
|
||||
.. delete:: /public/rest/v2/share/(int:share_id)
|
||||
|
||||
:synopsis: Delete a share
|
||||
|
||||
.. versionadded:: 3.0.0
|
||||
|
||||
:>json string status: ``success`` or ``error``
|
||||
|
||||
**Example:**
|
||||
|
||||
.. sourcecode:: http
|
||||
|
||||
POST /index.php/apps/bookmarks/public/rest/v2/share/17 HTTP/1.1
|
||||
Host: example.com
|
||||
Accept: application/json
|
||||
|
||||
**Response:**
|
||||
|
||||
.. sourcecode:: http
|
||||
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"status": "success",
|
||||
}
|
||||
Loading…
Reference in New Issue