13ff9ac4f8
* Allow marking bookmarks as unread * Restructure navigation to include preset filters * Add mark as read action * Improve description * Highlight unread bookmarks visually * Mark bookmarks as read by default * Add tests * Implement toread flag in importer * Implement admin actions * Add query tests * Remove untagged link * Update api docs * Reduce height of description textarea Co-authored-by: Sascha Ißbrücker <sascha.issbruecker@gmail.com>
3.6 KiB
API
The application provides a REST API that can be used by 3rd party applications to manage bookmarks.
Authentication
All requests against the API must be authorized using an authorization token. The application automatically generates an API token for each user, which can be accessed through the Settings page.
The token needs to be passed as Authorization header in the HTTP request:
Authorization: Token <Token>
Resources
The following resources are available:
Bookmarks
List
GET /api/bookmarks/
List bookmarks.
Parameters:
q- Filters results using a search phrase using the same logic as through the UIlimit- Limits the max. number of results. Default is100.offset- Index from which to start returning results
Example response:
{
"count": 123,
"next": "http://127.0.0.1:8000/api/bookmarks/?limit=100&offset=100",
"previous": null,
"results": [
{
"id": 1,
"url": "https://example.com",
"title": "Example title",
"description": "Example description",
"website_title": "Website title",
"website_description": "Website description",
"is_archived": false,
"unread": false,
"tag_names": [
"tag1",
"tag2"
],
"date_added": "2020-09-26T09:46:23.006313Z",
"date_modified": "2020-09-26T16:01:14.275335Z"
},
...
]
}
List Archived
GET /api/bookmarks/archived/
List archived bookmarks.
Parameters and response are the same as for the regular list endpoint.
Retrieve
GET /api/bookmarks/<id>/
Retrieves a single bookmark by ID.
Create
POST /api/bookmarks/
Creates a new bookmark. Tags are simply assigned using their names. Including
is_archived: true saves a bookmark directly to the archive.
Example payload:
{
"url": "https://example.com",
"title": "Example title",
"description": "Example description",
"is_archived": false,
"unread": false,
"tag_names": [
"tag1",
"tag2"
]
}
Update
PUT /api/bookmarks/<id>/
Updates a bookmark. This is a full update, which requires at least a URL, and fields that are not specified are cleared or reset to their defaults. Tags are simply assigned using their names.
Example payload:
{
"url": "https://example.com",
"title": "Example title",
"description": "Example description",
"tag_names": [
"tag1",
"tag2"
]
}
Patch
PATCH /api/bookmarks/<id>/
Updates a bookmark partially. Allows to modify individual fields of a bookmark. Tags are simply assigned using their names.
Example payload:
{
"url": "https://example.com",
"title": "Example title",
"description": "Example description",
"tag_names": [
"tag1",
"tag2"
]
}
Archive
POST /api/bookmarks/<id>/archive/
Archives a bookmark.
Unarchive
POST /api/bookmarks/<id>/unarchive/
Unarchives a bookmark.
Delete
DELETE /api/bookmarks/<id>/
Deletes a bookmark by ID.
Tags
List
GET /api/tags/
List tags.
Parameters:
limit- Limits the max. number of results. Default is100.offset- Index from which to start returning results
Example response:
{
"count": 123,
"next": "http://127.0.0.1:8000/api/tags/?limit=100&offset=100",
"previous": null,
"results": [
{
"id": 1,
"name": "example",
"date_added": "2020-09-26T09:46:23.006313Z"
},
...
]
}
Retrieve
GET /api/tags/<id>/
Retrieves a single tag by ID.
Create
POST /api/tags/
Creates a new tag.
Example payload:
{
"name": "example"
}