Skip to content

Latest commit

 

History

History
204 lines (146 loc) · 2.99 KB

API.md

File metadata and controls

204 lines (146 loc) · 2.99 KB
Raw

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 UI
  • limit - Limits the max. number of results. Default is 100.
  • 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",
      "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.

Example payload:

{
  "url": "https://example.com",
  "title": "Example title",
  "description": "Example description",
  "tag_names": [
    "tag1",
    "tag2"
  ]
}

Update

PUT /api/bookmarks/<id>/

Updates 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 is 100.
  • 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"
}