cleanup old api files
This commit is contained in:
Ilyas Hallak
parent
c1eb2109ed
commit
fe02668117
@ -1,563 +0,0 @@
|
|||||||
---
|
|
||||||
# SPDX-FileCopyrightText: © 2023 Olivier Meunier <olivier@neokraft.net>
|
|
||||||
#
|
|
||||||
# SPDX-License-Identifier: AGPL-3.0-only
|
|
||||||
|
|
||||||
withBookmark:
|
|
||||||
parameters:
|
|
||||||
- name: id
|
|
||||||
in: path
|
|
||||||
required: true
|
|
||||||
description: Bookmark ID
|
|
||||||
schema:
|
|
||||||
type: string
|
|
||||||
format: short-uid
|
|
||||||
|
|
||||||
withLabel:
|
|
||||||
parameters:
|
|
||||||
- name: name
|
|
||||||
in: path
|
|
||||||
required: true
|
|
||||||
description: Label
|
|
||||||
schema:
|
|
||||||
type: string
|
|
||||||
|
|
||||||
withAnnotation:
|
|
||||||
parameters:
|
|
||||||
- name: annotation_id
|
|
||||||
in: path
|
|
||||||
required: true
|
|
||||||
description: Highlight ID
|
|
||||||
schema:
|
|
||||||
type: string
|
|
||||||
format: short-uid
|
|
||||||
|
|
||||||
withCollection:
|
|
||||||
parameters:
|
|
||||||
- name: id
|
|
||||||
in: path
|
|
||||||
required: true
|
|
||||||
description: Collection ID
|
|
||||||
schema:
|
|
||||||
type: string
|
|
||||||
format: short-uid
|
|
||||||
|
|
||||||
# GET /bookmarks
|
|
||||||
list:
|
|
||||||
summary: Bookmark List
|
|
||||||
description: |
|
|
||||||
This route returns a paginated bookmark list.
|
|
||||||
|
|
||||||
parameters:
|
|
||||||
- name: search
|
|
||||||
in: query
|
|
||||||
description: A full text search string
|
|
||||||
schema:
|
|
||||||
type: string
|
|
||||||
- name: title
|
|
||||||
in: query
|
|
||||||
description: Bookmark title
|
|
||||||
schema:
|
|
||||||
type: string
|
|
||||||
- name: author
|
|
||||||
in: query
|
|
||||||
description: Author's name
|
|
||||||
schema:
|
|
||||||
type: string
|
|
||||||
- name: site
|
|
||||||
in: query
|
|
||||||
description: Bookmark site name or domain
|
|
||||||
schema:
|
|
||||||
type: string
|
|
||||||
- name: type
|
|
||||||
in: query
|
|
||||||
description: Bookmark type
|
|
||||||
schema:
|
|
||||||
type: array
|
|
||||||
items:
|
|
||||||
type: string
|
|
||||||
enum: [article, photo, video]
|
|
||||||
- name: labels
|
|
||||||
in: query
|
|
||||||
description: One or several labels
|
|
||||||
schema:
|
|
||||||
type: string
|
|
||||||
- name: is_loaded
|
|
||||||
in: query
|
|
||||||
description: Filter by loaded state
|
|
||||||
schema:
|
|
||||||
type: boolean
|
|
||||||
- name: has_errors
|
|
||||||
in: query
|
|
||||||
description: Filter bookmarks with or without errors
|
|
||||||
schema:
|
|
||||||
type: boolean
|
|
||||||
- name: has_labels
|
|
||||||
in: query
|
|
||||||
description: Filter bookmarks with or without labels
|
|
||||||
schema:
|
|
||||||
type: boolean
|
|
||||||
- name: is_marked
|
|
||||||
in: query
|
|
||||||
description: Filter by marked (favorite) status
|
|
||||||
schema:
|
|
||||||
type: boolean
|
|
||||||
- name: is_archived
|
|
||||||
in: query
|
|
||||||
description: Filter by archived status
|
|
||||||
schema:
|
|
||||||
type: boolean
|
|
||||||
- name: range_start
|
|
||||||
in: query
|
|
||||||
schema:
|
|
||||||
type: string
|
|
||||||
- name: range_end
|
|
||||||
in: query
|
|
||||||
schema:
|
|
||||||
type: string
|
|
||||||
- name: read_status
|
|
||||||
in: query
|
|
||||||
description: Read progress status
|
|
||||||
schema:
|
|
||||||
type: array
|
|
||||||
items:
|
|
||||||
type: string
|
|
||||||
enum: [unread, reading, read]
|
|
||||||
- name: updated_since
|
|
||||||
in: query
|
|
||||||
description: Retrieve bookmarks created after this date
|
|
||||||
schema:
|
|
||||||
type: string
|
|
||||||
format: date-time
|
|
||||||
- name: id
|
|
||||||
in: query
|
|
||||||
description: One or more bookmark ID
|
|
||||||
schema:
|
|
||||||
type: string
|
|
||||||
- name: collection
|
|
||||||
in: query
|
|
||||||
description: A collection ID
|
|
||||||
schema:
|
|
||||||
type: string
|
|
||||||
|
|
||||||
responses:
|
|
||||||
'200':
|
|
||||||
description: List of bookmark items
|
|
||||||
content:
|
|
||||||
application/json:
|
|
||||||
schema:
|
|
||||||
type: array
|
|
||||||
items:
|
|
||||||
$ref: "#/components/schemas/bookmarkSummary"
|
|
||||||
|
|
||||||
# POST /bookmarks
|
|
||||||
create:
|
|
||||||
summary: Bookmark Create
|
|
||||||
description: Creates a new bookmark
|
|
||||||
|
|
||||||
requestBody:
|
|
||||||
content:
|
|
||||||
application/json:
|
|
||||||
schema:
|
|
||||||
$ref: "#/components/schemas/bookmarkCreate"
|
|
||||||
|
|
||||||
responses:
|
|
||||||
"202":
|
|
||||||
headers:
|
|
||||||
Bookmark-Id:
|
|
||||||
schema:
|
|
||||||
type: string
|
|
||||||
description: ID of the created bookmark
|
|
||||||
|
|
||||||
# GET /bookmarks/{id}
|
|
||||||
retrieve:
|
|
||||||
summary: Bookmark Details
|
|
||||||
description: Retrieves a saved bookmark
|
|
||||||
|
|
||||||
responses:
|
|
||||||
"200":
|
|
||||||
description: Bookmark details
|
|
||||||
content:
|
|
||||||
application/json:
|
|
||||||
schema:
|
|
||||||
$ref: "#/components/schemas/bookmarkInfo"
|
|
||||||
|
|
||||||
# PATCH /bookmarks/{id}
|
|
||||||
update:
|
|
||||||
summary: Bookmark Update
|
|
||||||
description: |
|
|
||||||
This route updates some bookmark's properties. Every input value is optional.
|
|
||||||
Upon success, it returns a mapping of changed values.
|
|
||||||
|
|
||||||
requestBody:
|
|
||||||
content:
|
|
||||||
application/json:
|
|
||||||
schema:
|
|
||||||
$ref: "#/components/schemas/bookmarkUpdate"
|
|
||||||
|
|
||||||
responses:
|
|
||||||
"200":
|
|
||||||
description: Bookmark updated
|
|
||||||
content:
|
|
||||||
application/json:
|
|
||||||
schema:
|
|
||||||
$ref: "#/components/schemas/bookmarkUpdated"
|
|
||||||
|
|
||||||
# DELETE /bookmarks/{id}
|
|
||||||
delete:
|
|
||||||
summary: Bookmark Delete
|
|
||||||
description: Deletes a saved bookmark
|
|
||||||
|
|
||||||
responses:
|
|
||||||
"204":
|
|
||||||
description: The bookmark was successfuly deleted.
|
|
||||||
|
|
||||||
# GET /bookmarks/{id}/article
|
|
||||||
article:
|
|
||||||
summary: Bookmark Article
|
|
||||||
description: |
|
|
||||||
This route returns the bookmark's article if it exists.
|
|
||||||
|
|
||||||
responses:
|
|
||||||
"200":
|
|
||||||
description: |
|
|
||||||
A `text/html` response, containing the article body.
|
|
||||||
Please note that it's only the fragment and not a full HTML document.
|
|
||||||
content:
|
|
||||||
text/html:
|
|
||||||
schema:
|
|
||||||
type: string
|
|
||||||
|
|
||||||
# GET /bookmarks/{id}/article.{format}
|
|
||||||
export:
|
|
||||||
summary: Bookmark Export
|
|
||||||
description: This route exports a bookmark to another format.
|
|
||||||
|
|
||||||
parameters:
|
|
||||||
- name: format
|
|
||||||
in: path
|
|
||||||
required: true
|
|
||||||
description: Export format
|
|
||||||
schema:
|
|
||||||
type: string
|
|
||||||
enum: [epub, md]
|
|
||||||
|
|
||||||
responses:
|
|
||||||
"200":
|
|
||||||
content:
|
|
||||||
application/epub+zip:
|
|
||||||
schema:
|
|
||||||
type: string
|
|
||||||
format: binary
|
|
||||||
text/markdown:
|
|
||||||
schema:
|
|
||||||
type: string
|
|
||||||
|
|
||||||
# GET /bookmarks/{id}/share/link
|
|
||||||
shareLink:
|
|
||||||
summary: Share by link
|
|
||||||
description: This route produces a publicly accessible link to share a bookmark.
|
|
||||||
|
|
||||||
responses:
|
|
||||||
"200":
|
|
||||||
description: Public link information
|
|
||||||
content:
|
|
||||||
application/json:
|
|
||||||
schema:
|
|
||||||
$ref: "#/components/schemas/bookmarkShareLink"
|
|
||||||
|
|
||||||
# POST /bookmarks/{id}/share/email
|
|
||||||
shareEmail:
|
|
||||||
summary: Share by email
|
|
||||||
description: This route sends a bookmark to an email address.
|
|
||||||
|
|
||||||
requestBody:
|
|
||||||
content:
|
|
||||||
application/json:
|
|
||||||
schema:
|
|
||||||
$ref: "#/components/schemas/bookmarkShareEmail"
|
|
||||||
|
|
||||||
responses:
|
|
||||||
"200":
|
|
||||||
description: Message sent
|
|
||||||
content:
|
|
||||||
application/json:
|
|
||||||
schema:
|
|
||||||
$ref: "#/components/schemas/message"
|
|
||||||
|
|
||||||
# GET /bookmarks/labels
|
|
||||||
labels:
|
|
||||||
summary: Label List
|
|
||||||
description: |
|
|
||||||
This route returns all the labels associated to a bookmark for the current user.
|
|
||||||
|
|
||||||
responses:
|
|
||||||
"200":
|
|
||||||
description: Label list
|
|
||||||
content:
|
|
||||||
application/json:
|
|
||||||
schema:
|
|
||||||
type: array
|
|
||||||
items:
|
|
||||||
$ref: "#/components/schemas/labelInfo"
|
|
||||||
|
|
||||||
# GET /bookmarks/labels/{name}
|
|
||||||
labelInfo:
|
|
||||||
summary: Label Info
|
|
||||||
description:
|
|
||||||
This route returns information about a given bookmark label.
|
|
||||||
|
|
||||||
responses:
|
|
||||||
"200":
|
|
||||||
description: Label information
|
|
||||||
content:
|
|
||||||
application/json:
|
|
||||||
schema:
|
|
||||||
type: array
|
|
||||||
items:
|
|
||||||
$ref: "#/components/schemas/labelInfo"
|
|
||||||
|
|
||||||
# PATCH /bookmarks/labels/{name}
|
|
||||||
labelUpdate:
|
|
||||||
summary: Label Update
|
|
||||||
description: |
|
|
||||||
This route renames a label.
|
|
||||||
|
|
||||||
requestBody:
|
|
||||||
content:
|
|
||||||
application/json:
|
|
||||||
schema:
|
|
||||||
$ref: "#/components/schemas/labelUpdate"
|
|
||||||
|
|
||||||
responses:
|
|
||||||
"200":
|
|
||||||
description: Label renamed
|
|
||||||
|
|
||||||
# DELETE /bookmarks/labels/{name}
|
|
||||||
labelDelete:
|
|
||||||
summary: Label Delete
|
|
||||||
description: |
|
|
||||||
This route remove a label from all associated bookmarks.
|
|
||||||
|
|
||||||
Please note that it does not remove the bookmarks themselves.
|
|
||||||
|
|
||||||
responses:
|
|
||||||
"204":
|
|
||||||
description: Label removed
|
|
||||||
|
|
||||||
# GET /bookmarks/annotations
|
|
||||||
annotationList:
|
|
||||||
summary: Highlight List
|
|
||||||
description: |
|
|
||||||
This route returns all the highlights created by the current user.
|
|
||||||
|
|
||||||
responses:
|
|
||||||
"200":
|
|
||||||
description: Highlight list
|
|
||||||
content:
|
|
||||||
application/json:
|
|
||||||
schema:
|
|
||||||
type: array
|
|
||||||
items:
|
|
||||||
$ref: "#/components/schemas/annotationSummary"
|
|
||||||
|
|
||||||
# GET /bookmarks/{id}annotations
|
|
||||||
bookmarkAnnotationList:
|
|
||||||
summary: Bookmark Highlights
|
|
||||||
description: |
|
|
||||||
This route returns a given bookmark's highlights.
|
|
||||||
|
|
||||||
responses:
|
|
||||||
"200":
|
|
||||||
description: Highlight list
|
|
||||||
content:
|
|
||||||
application/json:
|
|
||||||
schema:
|
|
||||||
type: array
|
|
||||||
items:
|
|
||||||
$ref: "#/components/schemas/annotationInfo"
|
|
||||||
|
|
||||||
# POST /bookmarks/{id}annotations
|
|
||||||
bookmarkAnnotationCreate:
|
|
||||||
summary: Highlight Create
|
|
||||||
description: |
|
|
||||||
This route creates a new highlight on a given bookmarks.
|
|
||||||
|
|
||||||
The highlight format is similar to the [Range API](https://developer.mozilla.org/en-US/docs/Web/API/Range)
|
|
||||||
with some differences:
|
|
||||||
|
|
||||||
- A range's start and end selectors are XPath selectors and must target an element.
|
|
||||||
- The offset is the text length from the begining of the selector, regardless of the traversed
|
|
||||||
potential children.
|
|
||||||
|
|
||||||
requestBody:
|
|
||||||
content:
|
|
||||||
application/json:
|
|
||||||
schema:
|
|
||||||
$ref: "#/components/schemas/annotationCreate"
|
|
||||||
|
|
||||||
responses:
|
|
||||||
"201":
|
|
||||||
description: Highlight created
|
|
||||||
content:
|
|
||||||
application/json:
|
|
||||||
schema:
|
|
||||||
$ref: "#/components/schemas/annotationInfo"
|
|
||||||
|
|
||||||
# PATCH /bookmarks/{id}annotations/{annotation_id}
|
|
||||||
bookmarkAnnotationUpdate:
|
|
||||||
summary: Highlight Update
|
|
||||||
description: |
|
|
||||||
This route updates then given highlight in the given bookmark.
|
|
||||||
|
|
||||||
requestBody:
|
|
||||||
content:
|
|
||||||
application/json:
|
|
||||||
schema:
|
|
||||||
$ref: "#/components/schemas/annotationUpdate"
|
|
||||||
|
|
||||||
responses:
|
|
||||||
"200":
|
|
||||||
description: Update result
|
|
||||||
content:
|
|
||||||
application/json:
|
|
||||||
schema:
|
|
||||||
properties:
|
|
||||||
updated:
|
|
||||||
type: string
|
|
||||||
format: date-time
|
|
||||||
annotations:
|
|
||||||
type: array
|
|
||||||
items:
|
|
||||||
$ref: "#/components/schemas/annotationInfo"
|
|
||||||
|
|
||||||
|
|
||||||
# DELETE /bookmarks/{id}annotations/{annotation_id}
|
|
||||||
bookmarkAnnotationDelete:
|
|
||||||
summary: Highlight Delete
|
|
||||||
description: |
|
|
||||||
This route removes the given highlight in the given bookmark.
|
|
||||||
|
|
||||||
responses:
|
|
||||||
"204":
|
|
||||||
description: Highlight removed
|
|
||||||
|
|
||||||
# GET /bookmarks/collections
|
|
||||||
collectionList:
|
|
||||||
summary: Collection List
|
|
||||||
description: |
|
|
||||||
This route returns all the current user's collections.
|
|
||||||
|
|
||||||
responses:
|
|
||||||
"200":
|
|
||||||
description: Collection list
|
|
||||||
content:
|
|
||||||
application/json:
|
|
||||||
schema:
|
|
||||||
type: array
|
|
||||||
items:
|
|
||||||
$ref: "#/components/schemas/collectionInfo"
|
|
||||||
|
|
||||||
# POST /bookmarks/collections
|
|
||||||
collectionCreate:
|
|
||||||
summary: Collection Create
|
|
||||||
description: |
|
|
||||||
This route creates a new collection.
|
|
||||||
|
|
||||||
requestBody:
|
|
||||||
content:
|
|
||||||
application/json:
|
|
||||||
schema:
|
|
||||||
$ref: "#/components/schemas/collectionCreate"
|
|
||||||
|
|
||||||
# GET /bookmarks/collections/{id}
|
|
||||||
collectionInfo:
|
|
||||||
summary: Collection Details
|
|
||||||
description: |
|
|
||||||
This route returns a given collection information.
|
|
||||||
|
|
||||||
responses:
|
|
||||||
"200":
|
|
||||||
description: Collection information
|
|
||||||
content:
|
|
||||||
application/json:
|
|
||||||
schema:
|
|
||||||
$ref: "#/components/schemas/collectionInfo"
|
|
||||||
|
|
||||||
# PATH /bookmarks/collections/{id}
|
|
||||||
collectionUpdate:
|
|
||||||
summary: Collection Update
|
|
||||||
description: |
|
|
||||||
This route updates a given collection. It returns a mapping of updated fields.
|
|
||||||
|
|
||||||
requestBody:
|
|
||||||
content:
|
|
||||||
application/json:
|
|
||||||
schema:
|
|
||||||
$ref: "#/components/schemas/collectionUpdate"
|
|
||||||
|
|
||||||
responses:
|
|
||||||
"200":
|
|
||||||
description: Updated fields
|
|
||||||
content:
|
|
||||||
application/json:
|
|
||||||
schema:
|
|
||||||
$ref: "#/components/schemas/collectionSummary"
|
|
||||||
|
|
||||||
# DELETE /bookmarks/collections/{id}
|
|
||||||
collectionDelete:
|
|
||||||
summary: Collection Delete
|
|
||||||
description: |
|
|
||||||
This route deletes a given collection.
|
|
||||||
|
|
||||||
responses:
|
|
||||||
"204":
|
|
||||||
description: Collection deleted
|
|
||||||
|
|
||||||
# POST /bookmarks/import/text
|
|
||||||
importMultipartGeneric:
|
|
||||||
requestBody:
|
|
||||||
content:
|
|
||||||
text/plain:
|
|
||||||
schema:
|
|
||||||
type: string
|
|
||||||
description: File content
|
|
||||||
multipart/form-data:
|
|
||||||
schema:
|
|
||||||
properties:
|
|
||||||
data:
|
|
||||||
type: string
|
|
||||||
format: binary
|
|
||||||
|
|
||||||
importTextFile:
|
|
||||||
summary: Import a Text File
|
|
||||||
description: |
|
|
||||||
This route creates bookmarks from a text file that contains one URL
|
|
||||||
per line.
|
|
||||||
|
|
||||||
importBrowserBookmarks:
|
|
||||||
summary: Import Browser Bookmarks
|
|
||||||
description: |
|
|
||||||
This route creates bookmarks from an HTML file generated by an export of a browser's
|
|
||||||
bookmarks.
|
|
||||||
|
|
||||||
importPocket:
|
|
||||||
summary: Import Pocket Saves
|
|
||||||
description: |
|
|
||||||
This route creates bookmarks from an HTML file generated by Pocket export tool.
|
|
||||||
Go to [https://getpocket.com/export](https://getpocket.com/export) to generate
|
|
||||||
such a file.
|
|
||||||
|
|
||||||
importWallabag:
|
|
||||||
summary: Import Wallabag Articles
|
|
||||||
description: |
|
|
||||||
This route imports articles from Wallabag using its API.
|
|
||||||
|
|
||||||
You must create an API client in Wallabag and use its "Client ID" and "Client Secret"
|
|
||||||
in this route's payload.
|
|
||||||
|
|
||||||
requestBody:
|
|
||||||
content:
|
|
||||||
application/json:
|
|
||||||
schema:
|
|
||||||
$ref: "#/components/schemas/wallabagImport"
|
|
||||||
@ -1,27 +0,0 @@
|
|||||||
---
|
|
||||||
# SPDX-FileCopyrightText: © 2024 Olivier Meunier <olivier@neokraft.net>
|
|
||||||
#
|
|
||||||
# SPDX-License-Identifier: AGPL-3.0-only
|
|
||||||
|
|
||||||
sortable:
|
|
||||||
parameters:
|
|
||||||
- name: sort
|
|
||||||
in: query
|
|
||||||
description: Sorting parameters
|
|
||||||
schema:
|
|
||||||
type: array
|
|
||||||
items:
|
|
||||||
type: string
|
|
||||||
enum:
|
|
||||||
- created
|
|
||||||
- -created
|
|
||||||
- domain
|
|
||||||
- -domain
|
|
||||||
- duration
|
|
||||||
- -duration
|
|
||||||
- published
|
|
||||||
- -published
|
|
||||||
- site
|
|
||||||
- -site
|
|
||||||
- title
|
|
||||||
- -title
|
|
||||||
@ -1,580 +0,0 @@
|
|||||||
---
|
|
||||||
# SPDX-FileCopyrightText: © 2023 Olivier Meunier <olivier@neokraft.net>
|
|
||||||
#
|
|
||||||
# SPDX-License-Identifier: AGPL-3.0-only
|
|
||||||
|
|
||||||
schemas:
|
|
||||||
bookmarkSummary:
|
|
||||||
type: object
|
|
||||||
properties:
|
|
||||||
id:
|
|
||||||
type: string
|
|
||||||
format: short-uid
|
|
||||||
description: Bookmark's ID
|
|
||||||
href:
|
|
||||||
type: string
|
|
||||||
format: uri
|
|
||||||
description: Link to the bookmark info
|
|
||||||
created:
|
|
||||||
type: string
|
|
||||||
format: date-time
|
|
||||||
description: Creation date
|
|
||||||
updated:
|
|
||||||
type: string
|
|
||||||
format: date-time
|
|
||||||
description: Last update
|
|
||||||
state:
|
|
||||||
type: integer
|
|
||||||
enum: [0, 1, 2]
|
|
||||||
description: |
|
|
||||||
Indicates the state of the bookmark.
|
|
||||||
- `0`: loaded
|
|
||||||
- `1`: error
|
|
||||||
- `2`: loading
|
|
||||||
loaded:
|
|
||||||
type: boolean
|
|
||||||
description: Becomes true when the bookmark is ready (regardless of its error state)
|
|
||||||
url:
|
|
||||||
type: string
|
|
||||||
format: uri
|
|
||||||
description: Bookmark's original URL
|
|
||||||
title:
|
|
||||||
type: string
|
|
||||||
description: Bookmark's title
|
|
||||||
site_name:
|
|
||||||
type: string
|
|
||||||
description: Bookmark's site name
|
|
||||||
site:
|
|
||||||
type: string
|
|
||||||
format: hostname
|
|
||||||
description: Bookmark's site host name
|
|
||||||
published:
|
|
||||||
type: [string]
|
|
||||||
format: date-time
|
|
||||||
nullable: true
|
|
||||||
description: Publication date. Can be `null` when unknown.
|
|
||||||
authors:
|
|
||||||
type: array
|
|
||||||
items:
|
|
||||||
type: string
|
|
||||||
description: Author list
|
|
||||||
lang:
|
|
||||||
type: string
|
|
||||||
description: Language Code
|
|
||||||
text_direction:
|
|
||||||
type: string
|
|
||||||
enum: [rtl, ltr]
|
|
||||||
description: |
|
|
||||||
Direction of the article's text. It can be empty when it's unknown.
|
|
||||||
document_type:
|
|
||||||
type: string
|
|
||||||
description: |
|
|
||||||
The bookmark document type. This is usualy the same value as `type` but it can differ
|
|
||||||
depending on the extraction process.
|
|
||||||
type:
|
|
||||||
type: string
|
|
||||||
enum: [article, photo, video]
|
|
||||||
description: |
|
|
||||||
The bookmark type. Unlike `document_type`, this can only be one of the 3 values.
|
|
||||||
has_article:
|
|
||||||
type: boolean
|
|
||||||
description: |
|
|
||||||
Indicates whether the bookmarks contains an article. Please not that
|
|
||||||
there can be an article on any type.
|
|
||||||
description:
|
|
||||||
type: string
|
|
||||||
description: |
|
|
||||||
Bookmark's short description, when it exists. It's always an unformatted text.
|
|
||||||
is_deleted:
|
|
||||||
type: boolean
|
|
||||||
description: |
|
|
||||||
`true` when the bookmark is scheduled for deletion.
|
|
||||||
is_marked:
|
|
||||||
type: boolean
|
|
||||||
description: |
|
|
||||||
`true` when the bookmark is in the favorites.
|
|
||||||
is_archived:
|
|
||||||
type: boolean
|
|
||||||
description: |
|
|
||||||
`true` when the bookmark is in the archives.
|
|
||||||
read_progress:
|
|
||||||
type: integer
|
|
||||||
minimum: 0
|
|
||||||
maximum: 100
|
|
||||||
description: Reading progress percentage.
|
|
||||||
labels:
|
|
||||||
type: array
|
|
||||||
items:
|
|
||||||
type: string
|
|
||||||
description: Bookmark's labels
|
|
||||||
word_count:
|
|
||||||
type: integer
|
|
||||||
minimum: 0
|
|
||||||
description: Number of words in the article, used to compute the reading time.
|
|
||||||
reading_time:
|
|
||||||
type: integer
|
|
||||||
minimum: 0
|
|
||||||
description: |
|
|
||||||
Duration of the article, in minutes. Either the actual duration for a
|
|
||||||
video or a reading time based on the word count.
|
|
||||||
resources:
|
|
||||||
type: object
|
|
||||||
description: |
|
|
||||||
This contains a list of resources associated with the bookmark.
|
|
||||||
The only fields that are always present are `log` and `props`.
|
|
||||||
The `article` field is only present when a bookmark provides a
|
|
||||||
text content. Other image fields depend on what was found during
|
|
||||||
extraction.
|
|
||||||
properties:
|
|
||||||
article:
|
|
||||||
$ref: "#/components/schemas/bookmarkResource"
|
|
||||||
description: Link to the article, when there is one.
|
|
||||||
icon:
|
|
||||||
$ref: "#/components/schemas/bookmarkResourceImage"
|
|
||||||
description: Link and information for the site icon.
|
|
||||||
image:
|
|
||||||
$ref: "#/components/schemas/bookmarkResourceImage"
|
|
||||||
description: Link and information for the article image.
|
|
||||||
thumbnail:
|
|
||||||
$ref: "#/components/schemas/bookmarkResourceImage"
|
|
||||||
description: Link and information for the article thumbnail.
|
|
||||||
log:
|
|
||||||
$ref: "#/components/schemas/bookmarkResource"
|
|
||||||
description: Link to the extraction log.
|
|
||||||
props:
|
|
||||||
$ref: "#/components/schemas/bookmarkResource"
|
|
||||||
description: Link to the bookmark's extra properties.
|
|
||||||
|
|
||||||
bookmarkResource:
|
|
||||||
type: object
|
|
||||||
properties:
|
|
||||||
src:
|
|
||||||
type: string
|
|
||||||
format: uri
|
|
||||||
description: URL of the resource
|
|
||||||
|
|
||||||
bookmarkResourceImage:
|
|
||||||
allOf:
|
|
||||||
- $ref: "#/components/schemas/bookmarkResource"
|
|
||||||
- type: object
|
|
||||||
properties:
|
|
||||||
height:
|
|
||||||
type: integer
|
|
||||||
description: Image height
|
|
||||||
width:
|
|
||||||
type: integer
|
|
||||||
description: Image width
|
|
||||||
|
|
||||||
bookmarkInfo:
|
|
||||||
allOf:
|
|
||||||
- $ref: "#/components/schemas/bookmarkSummary"
|
|
||||||
- type: object
|
|
||||||
properties:
|
|
||||||
read_anchor:
|
|
||||||
type: string
|
|
||||||
description: CSS selector of the last seen element.
|
|
||||||
links:
|
|
||||||
description: |
|
|
||||||
This contains the list of all the links collected in the
|
|
||||||
retrieved article.
|
|
||||||
type: array
|
|
||||||
items:
|
|
||||||
properties:
|
|
||||||
url:
|
|
||||||
type: string
|
|
||||||
format: uri
|
|
||||||
description: Link URI
|
|
||||||
domain:
|
|
||||||
type: string
|
|
||||||
format: hostname
|
|
||||||
description: Link's domain
|
|
||||||
title:
|
|
||||||
type: string
|
|
||||||
description: Link's title
|
|
||||||
is_page:
|
|
||||||
type: boolean
|
|
||||||
description: |
|
|
||||||
`true` when the destination is a web page
|
|
||||||
content_type:
|
|
||||||
type: string
|
|
||||||
description: MIME type of the destination
|
|
||||||
|
|
||||||
bookmarkCreate:
|
|
||||||
required: [url]
|
|
||||||
properties:
|
|
||||||
url:
|
|
||||||
type: string
|
|
||||||
description: URL to fetch
|
|
||||||
title:
|
|
||||||
type: string
|
|
||||||
description: Title of the bookmark
|
|
||||||
labels:
|
|
||||||
type: array
|
|
||||||
items:
|
|
||||||
type: string
|
|
||||||
description: List of labels to set to the bookmark
|
|
||||||
|
|
||||||
bookmarkUpdate:
|
|
||||||
properties:
|
|
||||||
title:
|
|
||||||
type: string
|
|
||||||
description: New bookmark's title
|
|
||||||
is_marked:
|
|
||||||
type: boolean
|
|
||||||
description: Favortie state
|
|
||||||
is_archived:
|
|
||||||
type: boolean
|
|
||||||
description: Archive state
|
|
||||||
is_deleted:
|
|
||||||
type: boolean
|
|
||||||
description: |
|
|
||||||
If `true`, schedules the bookmark for deletion, otherwise, cancels any scheduled deletion
|
|
||||||
read_progress:
|
|
||||||
type: integer
|
|
||||||
minimum: 0
|
|
||||||
maximum: 100
|
|
||||||
description: Reading progress percentage
|
|
||||||
read_anchor:
|
|
||||||
type: string
|
|
||||||
description: CSS selector of the last seen element
|
|
||||||
labels:
|
|
||||||
type: array
|
|
||||||
items:
|
|
||||||
type: string
|
|
||||||
description: Replaces the bookmark's labels
|
|
||||||
add_labels:
|
|
||||||
items:
|
|
||||||
type: string
|
|
||||||
description: Add the given labels to the bookmark
|
|
||||||
remove_labels:
|
|
||||||
items:
|
|
||||||
type: string
|
|
||||||
description: Remove the given labels from the bookmark
|
|
||||||
|
|
||||||
bookmarkUpdated:
|
|
||||||
required: [href, id, updated]
|
|
||||||
properties:
|
|
||||||
href:
|
|
||||||
type: string
|
|
||||||
format: uri
|
|
||||||
description: Bookmark URI
|
|
||||||
id:
|
|
||||||
type: string
|
|
||||||
format: short-uid
|
|
||||||
description: Bookmark's ID
|
|
||||||
updated:
|
|
||||||
type: string
|
|
||||||
format: date-time
|
|
||||||
description: Last update
|
|
||||||
title:
|
|
||||||
type: string
|
|
||||||
description: Bookmark Title
|
|
||||||
is_marked:
|
|
||||||
type: string
|
|
||||||
description: Favorite status
|
|
||||||
is_archived:
|
|
||||||
type: string
|
|
||||||
description: Archive status
|
|
||||||
is_deleted:
|
|
||||||
type: string
|
|
||||||
description: Scheduled deletion status
|
|
||||||
read_progress:
|
|
||||||
type: integer
|
|
||||||
minimum: 0
|
|
||||||
maximum: 100
|
|
||||||
description: Reading progress percentage
|
|
||||||
read_anchor:
|
|
||||||
type: string
|
|
||||||
description: CSS selector of the last seen element
|
|
||||||
labels:
|
|
||||||
type: string
|
|
||||||
description: New label list
|
|
||||||
|
|
||||||
bookmarkShareLink:
|
|
||||||
properties:
|
|
||||||
url:
|
|
||||||
type: string
|
|
||||||
description: Public URL
|
|
||||||
expires:
|
|
||||||
type: string
|
|
||||||
format: date-time
|
|
||||||
description: Expiration date
|
|
||||||
title:
|
|
||||||
type: string
|
|
||||||
description: Bookmark title
|
|
||||||
id:
|
|
||||||
type: string
|
|
||||||
description: Bookmark ID
|
|
||||||
|
|
||||||
bookmarkShareEmail:
|
|
||||||
properties:
|
|
||||||
email:
|
|
||||||
type: string
|
|
||||||
format: email
|
|
||||||
format:
|
|
||||||
type: string
|
|
||||||
enum: ["html", "epub"]
|
|
||||||
example:
|
|
||||||
email: alice@localhost
|
|
||||||
format: html
|
|
||||||
|
|
||||||
labelInfo:
|
|
||||||
properties:
|
|
||||||
name:
|
|
||||||
type: string
|
|
||||||
description: Label's name
|
|
||||||
count:
|
|
||||||
type: integer
|
|
||||||
description: Number of bookmarks with this label
|
|
||||||
href:
|
|
||||||
type: string
|
|
||||||
format: uri
|
|
||||||
description: Link to the label info
|
|
||||||
href_bookmarks:
|
|
||||||
type: string
|
|
||||||
format: uri
|
|
||||||
description: Link to the bookmarks with this label
|
|
||||||
|
|
||||||
labelUpdate:
|
|
||||||
properties:
|
|
||||||
name:
|
|
||||||
type: string
|
|
||||||
description: New label
|
|
||||||
|
|
||||||
annotationSummary:
|
|
||||||
properties:
|
|
||||||
id:
|
|
||||||
type: string
|
|
||||||
format: short-uid
|
|
||||||
description: Highlight ID
|
|
||||||
href:
|
|
||||||
type: string
|
|
||||||
format: uri
|
|
||||||
description: Link to the highlight
|
|
||||||
text:
|
|
||||||
type: string
|
|
||||||
description: Highlighted text
|
|
||||||
created:
|
|
||||||
type: string
|
|
||||||
format: date-time
|
|
||||||
description: Highlight creation date
|
|
||||||
bookmark_id:
|
|
||||||
type: string
|
|
||||||
format: short-uid
|
|
||||||
description: Bookmark ID
|
|
||||||
bookmark_href:
|
|
||||||
type: string
|
|
||||||
format: uri
|
|
||||||
description: Link to the bookmark information
|
|
||||||
bookmark_url:
|
|
||||||
type: string
|
|
||||||
format: uri
|
|
||||||
description: Original bookmark's URL
|
|
||||||
bookmark_title:
|
|
||||||
type: string
|
|
||||||
description: Title of the bookmark
|
|
||||||
bookmark_site_name:
|
|
||||||
type: string
|
|
||||||
description: Bookmark's site name
|
|
||||||
|
|
||||||
annotationInfo:
|
|
||||||
properties:
|
|
||||||
id:
|
|
||||||
type: string
|
|
||||||
format: short-uid
|
|
||||||
description: Highlight ID
|
|
||||||
start_selector:
|
|
||||||
type: string
|
|
||||||
description: Start element's XPath selector
|
|
||||||
start_offset:
|
|
||||||
type: integer
|
|
||||||
description: Start element's text offset
|
|
||||||
end_selector:
|
|
||||||
type: string
|
|
||||||
description: End element's XPath selector
|
|
||||||
end_offset:
|
|
||||||
type: integer
|
|
||||||
description: End element's text offset
|
|
||||||
created:
|
|
||||||
type: string
|
|
||||||
format: date-time
|
|
||||||
description: Highlight creation date
|
|
||||||
text:
|
|
||||||
type: string
|
|
||||||
description: Highlighted text
|
|
||||||
|
|
||||||
annotationCreate:
|
|
||||||
required: [start_selector, start_offset, end_selector, end_offset, color]
|
|
||||||
properties:
|
|
||||||
start_selector:
|
|
||||||
type: string
|
|
||||||
description: Start element's XPath selector
|
|
||||||
start_offset:
|
|
||||||
type: integer
|
|
||||||
description: Start element's text offset
|
|
||||||
end_selector:
|
|
||||||
type: string
|
|
||||||
description: End element's XPath selector
|
|
||||||
end_offset:
|
|
||||||
type: integer
|
|
||||||
description: End element's text offset
|
|
||||||
color:
|
|
||||||
type: color
|
|
||||||
description: Annotation color
|
|
||||||
|
|
||||||
annotationUpdate:
|
|
||||||
required: [color]
|
|
||||||
properties:
|
|
||||||
color:
|
|
||||||
type: color
|
|
||||||
description: Annotation color
|
|
||||||
|
|
||||||
collectionSummary:
|
|
||||||
properties:
|
|
||||||
updated:
|
|
||||||
type: string
|
|
||||||
format: date-time
|
|
||||||
description: Last update date
|
|
||||||
name:
|
|
||||||
type: string
|
|
||||||
description: Collection's name
|
|
||||||
is_pinned:
|
|
||||||
type: boolean
|
|
||||||
description: |
|
|
||||||
`true` when the collection is pinned
|
|
||||||
is_deleted:
|
|
||||||
type: boolean
|
|
||||||
description: Collection is scheduled for deletion
|
|
||||||
search:
|
|
||||||
type: string
|
|
||||||
description: Search string
|
|
||||||
title:
|
|
||||||
type: string
|
|
||||||
description: Title filter
|
|
||||||
author:
|
|
||||||
type: string
|
|
||||||
description: Author filter
|
|
||||||
site:
|
|
||||||
type: string
|
|
||||||
description: Site (name, host or domain) filter
|
|
||||||
type:
|
|
||||||
type: array
|
|
||||||
items:
|
|
||||||
type: string
|
|
||||||
enum: [article, photo, video]
|
|
||||||
description: Type filter
|
|
||||||
labels:
|
|
||||||
type: string
|
|
||||||
description: Label filter
|
|
||||||
read_status:
|
|
||||||
type: array
|
|
||||||
items:
|
|
||||||
type: string
|
|
||||||
enum: [unread, reading, read]
|
|
||||||
description: Read progress status
|
|
||||||
is_marked:
|
|
||||||
type: boolean
|
|
||||||
description: Favorite filter
|
|
||||||
is_archived:
|
|
||||||
type: boolean
|
|
||||||
description: Archive filter
|
|
||||||
range_start:
|
|
||||||
type: string
|
|
||||||
description: From date filter
|
|
||||||
range_end:
|
|
||||||
type: string
|
|
||||||
description: To date filter
|
|
||||||
|
|
||||||
collectionInfo:
|
|
||||||
allOf:
|
|
||||||
- type: object
|
|
||||||
properties:
|
|
||||||
id:
|
|
||||||
type: string
|
|
||||||
format: short-uid
|
|
||||||
description: Collection ID
|
|
||||||
href:
|
|
||||||
type: string
|
|
||||||
format: uri
|
|
||||||
description: Collection URL
|
|
||||||
created:
|
|
||||||
type: string
|
|
||||||
format: date-time
|
|
||||||
description: Creation date
|
|
||||||
- $ref: "#/components/schemas/collectionSummary"
|
|
||||||
|
|
||||||
|
|
||||||
collectionCreate:
|
|
||||||
properties:
|
|
||||||
name:
|
|
||||||
type: string
|
|
||||||
description: Collection's name
|
|
||||||
is_pinned:
|
|
||||||
type: boolean
|
|
||||||
description: |
|
|
||||||
`true` when the collection is pinned
|
|
||||||
is_deleted:
|
|
||||||
type: boolean
|
|
||||||
description: Collection is scheduled for deletion
|
|
||||||
search:
|
|
||||||
type: string
|
|
||||||
description: Search string
|
|
||||||
title:
|
|
||||||
type: string
|
|
||||||
description: Title filter
|
|
||||||
author:
|
|
||||||
type: string
|
|
||||||
description: Author filter
|
|
||||||
site:
|
|
||||||
type: string
|
|
||||||
description: Site (name, host or domain) filter
|
|
||||||
type:
|
|
||||||
type: array
|
|
||||||
items:
|
|
||||||
type: string
|
|
||||||
enum: [article, photo, video]
|
|
||||||
description: Type filter
|
|
||||||
labels:
|
|
||||||
type: string
|
|
||||||
description: Label filter
|
|
||||||
read_status:
|
|
||||||
type: array
|
|
||||||
items:
|
|
||||||
type: string
|
|
||||||
enum: [unread, reading, read]
|
|
||||||
description: Read progress status
|
|
||||||
is_marked:
|
|
||||||
type: boolean
|
|
||||||
description: Favorite filter
|
|
||||||
is_archived:
|
|
||||||
type: boolean
|
|
||||||
description: Archive filter
|
|
||||||
range_start:
|
|
||||||
type: string
|
|
||||||
description: From date filter
|
|
||||||
range_end:
|
|
||||||
type: string
|
|
||||||
description: To date filter
|
|
||||||
|
|
||||||
collectionUpdate:
|
|
||||||
allOf:
|
|
||||||
- $ref: "#/components/schemas/collectionCreate"
|
|
||||||
|
|
||||||
wallabagImport:
|
|
||||||
properties:
|
|
||||||
url:
|
|
||||||
type: string
|
|
||||||
format: uri
|
|
||||||
description: Your Wallabag instance's URL
|
|
||||||
username:
|
|
||||||
type: string
|
|
||||||
description: Your Wallabag username
|
|
||||||
password:
|
|
||||||
type: string
|
|
||||||
description: Your Wallabag password
|
|
||||||
client_id:
|
|
||||||
type: string
|
|
||||||
description: API Client ID
|
|
||||||
client_secret:
|
|
||||||
type: string
|
|
||||||
description: API Client Secret
|
|
||||||
@ -1,145 +0,0 @@
|
|||||||
---
|
|
||||||
# SPDX-FileCopyrightText: © 2023 Olivier Meunier <olivier@neokraft.net>
|
|
||||||
#
|
|
||||||
# SPDX-License-Identifier: AGPL-3.0-only
|
|
||||||
|
|
||||||
# GET /cookbook/extrack
|
|
||||||
extract:
|
|
||||||
summary: Extract Link
|
|
||||||
description: |
|
|
||||||
**NOTE: Only available for user in the admin group.**
|
|
||||||
|
|
||||||
This route extracts a link and returns the extraction result.
|
|
||||||
|
|
||||||
You can pass an `Accept` header to the request, with one of the following values:
|
|
||||||
|
|
||||||
- `application/json` (default) returns a JSON response
|
|
||||||
- `text/html` returns an HTML response with all the media included as base64 encoded
|
|
||||||
URLs.
|
|
||||||
|
|
||||||
parameters:
|
|
||||||
- name: url
|
|
||||||
in: query
|
|
||||||
required: true
|
|
||||||
schema:
|
|
||||||
type: string
|
|
||||||
format: uri
|
|
||||||
description: URL to extract
|
|
||||||
|
|
||||||
responses:
|
|
||||||
"200":
|
|
||||||
description: |
|
|
||||||
Extraction result.
|
|
||||||
content:
|
|
||||||
application/json:
|
|
||||||
schema:
|
|
||||||
properties:
|
|
||||||
url:
|
|
||||||
type: string
|
|
||||||
format: uri
|
|
||||||
description: The extracted URL
|
|
||||||
logs:
|
|
||||||
type: array
|
|
||||||
items:
|
|
||||||
type: string
|
|
||||||
description: Extraction log
|
|
||||||
errors:
|
|
||||||
type: array
|
|
||||||
items:
|
|
||||||
type: string
|
|
||||||
description: Extraction errors, if any
|
|
||||||
meta:
|
|
||||||
type: object
|
|
||||||
additionalProperties:
|
|
||||||
type: array
|
|
||||||
items:
|
|
||||||
type: string
|
|
||||||
description: |
|
|
||||||
Contains the meta tags extracted from the page.
|
|
||||||
properties:
|
|
||||||
properties:
|
|
||||||
json-ld:
|
|
||||||
type: array
|
|
||||||
items:
|
|
||||||
type: object
|
|
||||||
description: A list of JSON-LD documents retrieved during the extraction
|
|
||||||
link:
|
|
||||||
type: array
|
|
||||||
items:
|
|
||||||
type: object
|
|
||||||
patternProperties:
|
|
||||||
"^@.+":
|
|
||||||
type: string
|
|
||||||
description: Link attribute, always starting with `@`
|
|
||||||
description: A list of all `link` tags retrieved during the extraction
|
|
||||||
meta:
|
|
||||||
type: array
|
|
||||||
items:
|
|
||||||
type: object
|
|
||||||
patternProperties:
|
|
||||||
"^@.+":
|
|
||||||
type: string
|
|
||||||
description: Meta attribute, always starting with `@`
|
|
||||||
description: A list of all `meta` tags retrieved during the extraction
|
|
||||||
domain:
|
|
||||||
type: string
|
|
||||||
format: hostname
|
|
||||||
description: Page's domain name
|
|
||||||
title:
|
|
||||||
type: string
|
|
||||||
description: Page's title
|
|
||||||
authors:
|
|
||||||
type: "[string]"
|
|
||||||
description: Page's author list
|
|
||||||
site:
|
|
||||||
type: string
|
|
||||||
format: hostname
|
|
||||||
description: Page's site
|
|
||||||
site_name:
|
|
||||||
type: string
|
|
||||||
description: Page's site name
|
|
||||||
lang:
|
|
||||||
type: string
|
|
||||||
description: Language Code
|
|
||||||
text_direction:
|
|
||||||
type: string
|
|
||||||
enum: [rtl, ltr]
|
|
||||||
description: |
|
|
||||||
Direction of the article's text. It can be empty when it's unknown.
|
|
||||||
date:
|
|
||||||
type: [string]
|
|
||||||
format: date-time
|
|
||||||
nullable: true
|
|
||||||
description: Publication date. Can be `null` when unknown.
|
|
||||||
document_type:
|
|
||||||
type: string
|
|
||||||
description: |
|
|
||||||
The detected document type. The value is usualy `article`, `photo` or `video`
|
|
||||||
but can vary, based on the extraction process.
|
|
||||||
description:
|
|
||||||
type: string
|
|
||||||
description: |
|
|
||||||
Page's short description, when it exists. It's always an unformatted text.
|
|
||||||
html:
|
|
||||||
type: string
|
|
||||||
description: |
|
|
||||||
The HTML content after processing.
|
|
||||||
embed:
|
|
||||||
type: string
|
|
||||||
description: |
|
|
||||||
The oembed HTML fragment, when it exists. It usualy contains an iframe when
|
|
||||||
extracting videos.
|
|
||||||
images:
|
|
||||||
properties:
|
|
||||||
additionalProperties:
|
|
||||||
properties:
|
|
||||||
size:
|
|
||||||
type: "[integer]"
|
|
||||||
description: The image size in pixels
|
|
||||||
encoded:
|
|
||||||
type: string
|
|
||||||
description: The base64 URI encoded image
|
|
||||||
|
|
||||||
text/html:
|
|
||||||
schema:
|
|
||||||
type: string
|
|
||||||
@ -1,339 +0,0 @@
|
|||||||
---
|
|
||||||
# SPDX-FileCopyrightText: © 2023 Olivier Meunier <olivier@neokraft.net>
|
|
||||||
#
|
|
||||||
# SPDX-License-Identifier: AGPL-3.0-only
|
|
||||||
|
|
||||||
openapi: 3.0.0
|
|
||||||
info:
|
|
||||||
version: 1.0.0
|
|
||||||
title: Readeck API
|
|
||||||
description: |
|
|
||||||
# Introduction
|
|
||||||
|
|
||||||
The Readeck API provides REST endpoints that can be used for any purpose, should it be a
|
|
||||||
mobile application, a script, you name it.
|
|
||||||
|
|
||||||
## API Endpoint
|
|
||||||
|
|
||||||
You can access this API on `__BASE_URI__`.
|
|
||||||
|
|
||||||
Most of your requests and responses are using JSON as the exchange format.
|
|
||||||
|
|
||||||
## Authentication
|
|
||||||
|
|
||||||
To use the API, you first need to [create an authentication token](../profile/tokens). You can
|
|
||||||
then use your new token using the `Bearer` HTTP authorization scheme.
|
|
||||||
|
|
||||||
For example, you first request will look like:
|
|
||||||
|
|
||||||
```sh
|
|
||||||
curl -H "Authorization: Bearer <TOKEN>" __BASE_URI__/bookmarks
|
|
||||||
```
|
|
||||||
|
|
||||||
Or, in NodeJS:
|
|
||||||
|
|
||||||
```js
|
|
||||||
fetch("__BASE_URI__/bookmarks", {
|
|
||||||
headers: {
|
|
||||||
"Authorization": "Bearer <TOKEN>",
|
|
||||||
},
|
|
||||||
})
|
|
||||||
```
|
|
||||||
|
|
||||||
## First time authentication
|
|
||||||
|
|
||||||
While you can create an authentication token from Readeck, you can also get one directly from
|
|
||||||
the API. This provides a mechanism to ask for user credentials and obtain a token for your app
|
|
||||||
only.
|
|
||||||
|
|
||||||
Please refer to [POST /auth](#post-/auth) for more information.
|
|
||||||
|
|
||||||
## Test the API
|
|
||||||
|
|
||||||
On this documentation, you can test every route.
|
|
||||||
|
|
||||||
If you don't provide an API token in [Authentication](#auth), you can still test all the routes
|
|
||||||
but note that the given curl examples only work with an API token.
|
|
||||||
|
|
||||||
|
|
||||||
servers:
|
|
||||||
- url: __BASE_URI__
|
|
||||||
|
|
||||||
components:
|
|
||||||
securitySchemes:
|
|
||||||
bearer:
|
|
||||||
type: http
|
|
||||||
scheme: Bearer
|
|
||||||
|
|
||||||
schemas:
|
|
||||||
$merge:
|
|
||||||
- "types.yaml#.schemas"
|
|
||||||
- "bookmarks/types.yaml#.schemas"
|
|
||||||
- "profile/types.yaml#.schemas"
|
|
||||||
|
|
||||||
security:
|
|
||||||
- bearer: []
|
|
||||||
|
|
||||||
tags:
|
|
||||||
- name: user profile
|
|
||||||
- name: bookmarks
|
|
||||||
- name: bookmark export
|
|
||||||
- name: bookmark sharing
|
|
||||||
- name: bookmark labels
|
|
||||||
- name: bookmark highlights
|
|
||||||
- name: bookmark collections
|
|
||||||
- name: bookmarks import
|
|
||||||
- name: dev tools
|
|
||||||
|
|
||||||
paths:
|
|
||||||
/auth:
|
|
||||||
post:
|
|
||||||
tags: [user profile]
|
|
||||||
$merge:
|
|
||||||
- "profile/routes.yaml#.auth"
|
|
||||||
|
|
||||||
/profile:
|
|
||||||
get:
|
|
||||||
tags: [user profile]
|
|
||||||
$merge:
|
|
||||||
- "traits.yaml#.authenticated"
|
|
||||||
- "profile/routes.yaml#.profile"
|
|
||||||
|
|
||||||
/bookmarks:
|
|
||||||
get:
|
|
||||||
tags: [bookmarks]
|
|
||||||
$merge:
|
|
||||||
- "traits.yaml#.authenticated"
|
|
||||||
- "traits.yaml#.paginated"
|
|
||||||
- "bookmarks/traits.yaml#.sortable"
|
|
||||||
- "bookmarks/routes.yaml#.list"
|
|
||||||
|
|
||||||
post:
|
|
||||||
tags: [bookmarks]
|
|
||||||
$merge:
|
|
||||||
- "traits.yaml#.authenticated"
|
|
||||||
- "traits.yaml#.validator"
|
|
||||||
- "traits.yaml#.deferred"
|
|
||||||
- "bookmarks/routes.yaml#.create"
|
|
||||||
|
|
||||||
/bookmarks/{id}:
|
|
||||||
$merge:
|
|
||||||
- "bookmarks/routes.yaml#.withBookmark"
|
|
||||||
|
|
||||||
get:
|
|
||||||
tags: [bookmarks]
|
|
||||||
$merge:
|
|
||||||
- "traits.yaml#.authenticated"
|
|
||||||
- "bookmarks/routes.yaml#.retrieve"
|
|
||||||
|
|
||||||
patch:
|
|
||||||
tags: [bookmarks]
|
|
||||||
$merge:
|
|
||||||
- "traits.yaml#.authenticated"
|
|
||||||
- "traits.yaml#.validator"
|
|
||||||
- "bookmarks/routes.yaml#.update"
|
|
||||||
|
|
||||||
delete:
|
|
||||||
tags: [bookmarks]
|
|
||||||
$merge:
|
|
||||||
- "traits.yaml#.authenticated"
|
|
||||||
- "bookmarks/routes.yaml#.delete"
|
|
||||||
|
|
||||||
/bookmarks/{id}/article:
|
|
||||||
$merge:
|
|
||||||
- "bookmarks/routes.yaml#.withBookmark"
|
|
||||||
|
|
||||||
get:
|
|
||||||
tags: [bookmark export]
|
|
||||||
$merge:
|
|
||||||
- "traits.yaml#.authenticated"
|
|
||||||
- "bookmarks/routes.yaml#.article"
|
|
||||||
|
|
||||||
/bookmarks/{id}/article.{format}:
|
|
||||||
$merge:
|
|
||||||
- "bookmarks/routes.yaml#.withBookmark"
|
|
||||||
|
|
||||||
get:
|
|
||||||
tags: [bookmark export]
|
|
||||||
$merge:
|
|
||||||
- "traits.yaml#.authenticated"
|
|
||||||
- "bookmarks/routes.yaml#.export"
|
|
||||||
|
|
||||||
/bookmarks/{id}/share/link:
|
|
||||||
$merge:
|
|
||||||
- "bookmarks/routes.yaml#.withBookmark"
|
|
||||||
|
|
||||||
get:
|
|
||||||
tags: [bookmark sharing]
|
|
||||||
$merge:
|
|
||||||
- "traits.yaml#.authenticated"
|
|
||||||
- "bookmarks/routes.yaml#.shareLink"
|
|
||||||
|
|
||||||
/bookmarks/{id}/share/email:
|
|
||||||
$merge:
|
|
||||||
- "bookmarks/routes.yaml#.withBookmark"
|
|
||||||
|
|
||||||
post:
|
|
||||||
tags: [bookmark sharing]
|
|
||||||
$merge:
|
|
||||||
- "traits.yaml#.authenticated"
|
|
||||||
- "bookmarks/routes.yaml#.shareEmail"
|
|
||||||
|
|
||||||
/bookmarks/labels:
|
|
||||||
get:
|
|
||||||
tags: [bookmark labels]
|
|
||||||
$merge:
|
|
||||||
- "traits.yaml#.authenticated"
|
|
||||||
- "bookmarks/routes.yaml#.labels"
|
|
||||||
|
|
||||||
/bookmarks/labels/{name}:
|
|
||||||
$merge:
|
|
||||||
- "bookmarks/routes.yaml#.withLabel"
|
|
||||||
|
|
||||||
get:
|
|
||||||
tags: [bookmark labels]
|
|
||||||
$merge:
|
|
||||||
- "traits.yaml#.authenticated"
|
|
||||||
- "bookmarks/routes.yaml#.labelInfo"
|
|
||||||
|
|
||||||
patch:
|
|
||||||
tags: [bookmark labels]
|
|
||||||
$merge:
|
|
||||||
- "traits.yaml#.authenticated"
|
|
||||||
- "traits.yaml#.validator"
|
|
||||||
- "bookmarks/routes.yaml#.labelUpdate"
|
|
||||||
|
|
||||||
delete:
|
|
||||||
tags: [bookmark labels]
|
|
||||||
$merge:
|
|
||||||
- "traits.yaml#.authenticated"
|
|
||||||
- "bookmarks/routes.yaml#.labelDelete"
|
|
||||||
|
|
||||||
/bookmarks/annotations:
|
|
||||||
get:
|
|
||||||
tags: [bookmark highlights]
|
|
||||||
$merge:
|
|
||||||
- "traits.yaml#.authenticated"
|
|
||||||
- "traits.yaml#.paginated"
|
|
||||||
- "bookmarks/routes.yaml#.annotationList"
|
|
||||||
|
|
||||||
/bookmarks/{id}/annotations:
|
|
||||||
$merge:
|
|
||||||
- "bookmarks/routes.yaml#.withBookmark"
|
|
||||||
|
|
||||||
get:
|
|
||||||
tags: [bookmark highlights]
|
|
||||||
$merge:
|
|
||||||
- "traits.yaml#.authenticated"
|
|
||||||
- "bookmarks/routes.yaml#.bookmarkAnnotationList"
|
|
||||||
|
|
||||||
post:
|
|
||||||
tags: [bookmark highlights]
|
|
||||||
$merge:
|
|
||||||
- "traits.yaml#.authenticated"
|
|
||||||
- "traits.yaml#.validator"
|
|
||||||
- "traits.yaml#.created"
|
|
||||||
- "bookmarks/routes.yaml#.bookmarkAnnotationCreate"
|
|
||||||
|
|
||||||
/bookmarks/{id}/annotations/{annotation_id}:
|
|
||||||
$merge:
|
|
||||||
- "bookmarks/routes.yaml#.withBookmark"
|
|
||||||
|
|
||||||
patch:
|
|
||||||
tags: [bookmark highlights]
|
|
||||||
$merge:
|
|
||||||
- "traits.yaml#.authenticated"
|
|
||||||
- "traits.yaml#.validator"
|
|
||||||
- "bookmarks/routes.yaml#.withAnnotation"
|
|
||||||
- "bookmarks/routes.yaml#.bookmarkAnnotationUpdate"
|
|
||||||
|
|
||||||
delete:
|
|
||||||
tags: [bookmark highlights]
|
|
||||||
$merge:
|
|
||||||
- "traits.yaml#.authenticated"
|
|
||||||
- "bookmarks/routes.yaml#.withAnnotation"
|
|
||||||
- "bookmarks/routes.yaml#.bookmarkAnnotationDelete"
|
|
||||||
|
|
||||||
/bookmarks/collections:
|
|
||||||
get:
|
|
||||||
tags: [bookmark collections]
|
|
||||||
$merge:
|
|
||||||
- "traits.yaml#.authenticated"
|
|
||||||
- "traits.yaml#.paginated"
|
|
||||||
- "bookmarks/routes.yaml#.collectionList"
|
|
||||||
|
|
||||||
post:
|
|
||||||
tags: [bookmark collections]
|
|
||||||
$merge:
|
|
||||||
- "traits.yaml#.authenticated"
|
|
||||||
- "traits.yaml#.created"
|
|
||||||
- "bookmarks/routes.yaml#.collectionCreate"
|
|
||||||
|
|
||||||
/bookmarks/collections/{id}:
|
|
||||||
$merge:
|
|
||||||
- "bookmarks/routes.yaml#.withCollection"
|
|
||||||
|
|
||||||
get:
|
|
||||||
tags: [bookmark collections]
|
|
||||||
$merge:
|
|
||||||
- "traits.yaml#.authenticated"
|
|
||||||
- "bookmarks/routes.yaml#.collectionInfo"
|
|
||||||
|
|
||||||
patch:
|
|
||||||
tags: [bookmark collections]
|
|
||||||
$merge:
|
|
||||||
- "traits.yaml#.authenticated"
|
|
||||||
- "bookmarks/routes.yaml#.collectionUpdate"
|
|
||||||
|
|
||||||
delete:
|
|
||||||
tags: [bookmark collections]
|
|
||||||
$merge:
|
|
||||||
- "traits.yaml#.authenticated"
|
|
||||||
- "bookmarks/routes.yaml#.collectionDelete"
|
|
||||||
|
|
||||||
/bookmarks/import/text:
|
|
||||||
post:
|
|
||||||
tags: [bookmarks import]
|
|
||||||
$merge:
|
|
||||||
- "traits.yaml#.authenticated"
|
|
||||||
- "traits.yaml#.validator"
|
|
||||||
- "traits.yaml#.deferred"
|
|
||||||
- "bookmarks/routes.yaml#.importMultipartGeneric"
|
|
||||||
- "bookmarks/routes.yaml#.importTextFile"
|
|
||||||
|
|
||||||
/bookmarks/import/browser:
|
|
||||||
post:
|
|
||||||
tags: [bookmarks import]
|
|
||||||
$merge:
|
|
||||||
- "traits.yaml#.authenticated"
|
|
||||||
- "traits.yaml#.validator"
|
|
||||||
- "traits.yaml#.deferred"
|
|
||||||
- "bookmarks/routes.yaml#.importMultipartGeneric"
|
|
||||||
- "bookmarks/routes.yaml#.importBrowserBookmarks"
|
|
||||||
|
|
||||||
/bookmarks/import/pocket-file:
|
|
||||||
post:
|
|
||||||
tags: [bookmarks import]
|
|
||||||
$merge:
|
|
||||||
- "traits.yaml#.authenticated"
|
|
||||||
- "traits.yaml#.validator"
|
|
||||||
- "traits.yaml#.deferred"
|
|
||||||
- "bookmarks/routes.yaml#.importMultipartGeneric"
|
|
||||||
- "bookmarks/routes.yaml#.importPocket"
|
|
||||||
|
|
||||||
/bookmarks/import/wallabag:
|
|
||||||
post:
|
|
||||||
tags: [bookmarks import]
|
|
||||||
$merge:
|
|
||||||
- "traits.yaml#.authenticated"
|
|
||||||
- "traits.yaml#.validator"
|
|
||||||
- "traits.yaml#.deferred"
|
|
||||||
- "bookmarks/routes.yaml#.importWallabag"
|
|
||||||
|
|
||||||
|
|
||||||
/cookbook/extract:
|
|
||||||
get:
|
|
||||||
tags: [dev tools]
|
|
||||||
$merge:
|
|
||||||
- "traits.yaml#.authenticated"
|
|
||||||
- "cookbook/routes.yaml#.extract"
|
|
||||||
@ -1,55 +0,0 @@
|
|||||||
---
|
|
||||||
# SPDX-FileCopyrightText: © 2023 Olivier Meunier <olivier@neokraft.net>
|
|
||||||
#
|
|
||||||
# SPDX-License-Identifier: AGPL-3.0-only
|
|
||||||
|
|
||||||
auth:
|
|
||||||
summary: Authenticate
|
|
||||||
description: |
|
|
||||||
This route performs the authentication with a username and a password and returns a token
|
|
||||||
that you can use for all API requests.
|
|
||||||
|
|
||||||
You don't need to perform a request to this route each time you're using the API, only do it
|
|
||||||
once and keep the token somehow. You can use this route to provide a first time authentication
|
|
||||||
in a mobile application or any API client you may build and only store the resulting token.
|
|
||||||
|
|
||||||
You MUST provide an application name.
|
|
||||||
|
|
||||||
Alternatively, you can [create an authentication token](../profile/tokens) directly from
|
|
||||||
Readeck.
|
|
||||||
|
|
||||||
requestBody:
|
|
||||||
content:
|
|
||||||
application/json:
|
|
||||||
schema:
|
|
||||||
$ref: "#/components/schemas/authenticationForm"
|
|
||||||
|
|
||||||
responses:
|
|
||||||
"201":
|
|
||||||
description: Authentication success
|
|
||||||
content:
|
|
||||||
application/json:
|
|
||||||
schema:
|
|
||||||
$ref: "#/components/schemas/authenticationResult"
|
|
||||||
|
|
||||||
"403":
|
|
||||||
description: Authentication failed
|
|
||||||
content:
|
|
||||||
application/json:
|
|
||||||
schema:
|
|
||||||
$ref: "#/components/schemas/message"
|
|
||||||
|
|
||||||
# GET /profile
|
|
||||||
profile:
|
|
||||||
summary: User Profile
|
|
||||||
description: |
|
|
||||||
This route returns the current user's profile information. This includes the user information
|
|
||||||
and preferences, and the authentication provider with its permissions.
|
|
||||||
|
|
||||||
responses:
|
|
||||||
"200":
|
|
||||||
description: Profile information
|
|
||||||
content:
|
|
||||||
application/json:
|
|
||||||
schema:
|
|
||||||
$ref: "#/components/schemas/userProfile"
|
|
||||||
@ -1,143 +0,0 @@
|
|||||||
---
|
|
||||||
# SPDX-FileCopyrightText: © 2023 Olivier Meunier <olivier@neokraft.net>
|
|
||||||
#
|
|
||||||
# SPDX-License-Identifier: AGPL-3.0-only
|
|
||||||
|
|
||||||
schemas:
|
|
||||||
authenticationForm:
|
|
||||||
type: object
|
|
||||||
required: [username, password, application]
|
|
||||||
properties:
|
|
||||||
username:
|
|
||||||
type: string
|
|
||||||
description: Username
|
|
||||||
password:
|
|
||||||
type: string
|
|
||||||
description: Password
|
|
||||||
application:
|
|
||||||
type: string
|
|
||||||
description: Application name. This can be anything.
|
|
||||||
roles:
|
|
||||||
type: array
|
|
||||||
items:
|
|
||||||
type: string
|
|
||||||
description: A list of roles to restrict the new token access.
|
|
||||||
example:
|
|
||||||
username: alice
|
|
||||||
password: "1234"
|
|
||||||
application: api doc
|
|
||||||
|
|
||||||
authenticationResult:
|
|
||||||
type: object
|
|
||||||
properties:
|
|
||||||
id:
|
|
||||||
type: string
|
|
||||||
description: Token ID
|
|
||||||
token:
|
|
||||||
type: string
|
|
||||||
description: Authentication token. This is the value you must store in your application.
|
|
||||||
example:
|
|
||||||
{
|
|
||||||
"id": "RFutYEAVM95DUDLUDnhbQm",
|
|
||||||
"token": "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9.eyJqdxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
|
|
||||||
}
|
|
||||||
|
|
||||||
userProfile:
|
|
||||||
type: object
|
|
||||||
properties:
|
|
||||||
provider:
|
|
||||||
description: Authentication provider information
|
|
||||||
type: object
|
|
||||||
properties:
|
|
||||||
id:
|
|
||||||
type: string
|
|
||||||
format: short-uid
|
|
||||||
description: Authentication provider ID (ie. the token ID)
|
|
||||||
name:
|
|
||||||
type: string
|
|
||||||
description: Provider name
|
|
||||||
application:
|
|
||||||
type: string
|
|
||||||
description: The registered application name
|
|
||||||
roles:
|
|
||||||
type: array
|
|
||||||
items:
|
|
||||||
type: string
|
|
||||||
description: Roles granted for this session
|
|
||||||
permissions:
|
|
||||||
type: array
|
|
||||||
items:
|
|
||||||
type: string
|
|
||||||
description: Permissions granted for this session
|
|
||||||
user:
|
|
||||||
description: User information
|
|
||||||
type: object
|
|
||||||
properties:
|
|
||||||
username:
|
|
||||||
type: string
|
|
||||||
description: Username
|
|
||||||
email:
|
|
||||||
type: string
|
|
||||||
format: email
|
|
||||||
description: User email
|
|
||||||
created:
|
|
||||||
type: string
|
|
||||||
format: date-time
|
|
||||||
description: Creation date
|
|
||||||
updated:
|
|
||||||
type: string
|
|
||||||
format: date-time
|
|
||||||
description: Last update date
|
|
||||||
settings:
|
|
||||||
description: User settings
|
|
||||||
type: object
|
|
||||||
properties:
|
|
||||||
debug_info:
|
|
||||||
type: boolean
|
|
||||||
description: Enable debug information
|
|
||||||
reader_settings:
|
|
||||||
description: Reader settings
|
|
||||||
type: object
|
|
||||||
properties:
|
|
||||||
font:
|
|
||||||
type: string
|
|
||||||
font_size:
|
|
||||||
type: integer
|
|
||||||
line_height:
|
|
||||||
type: integer
|
|
||||||
example:
|
|
||||||
{
|
|
||||||
"provider": {
|
|
||||||
"name": "bearer token",
|
|
||||||
"id": "X4bmnMRcnDhQtu5y33qzTp",
|
|
||||||
"application": "internal",
|
|
||||||
"roles": [
|
|
||||||
"scoped_bookmarks_r",
|
|
||||||
"scoped_bookmarks_w"
|
|
||||||
],
|
|
||||||
"permissions": [
|
|
||||||
"api:bookmarks:collections:read",
|
|
||||||
"api:bookmarks:collections:write",
|
|
||||||
"api:bookmarks:export",
|
|
||||||
"api:bookmarks:read",
|
|
||||||
"api:bookmarks:write",
|
|
||||||
"api:opds:read",
|
|
||||||
"api:profile:read",
|
|
||||||
"api:profile:tokens:delete"
|
|
||||||
]
|
|
||||||
},
|
|
||||||
"user": {
|
|
||||||
"username": "alice",
|
|
||||||
"email": "alice@localhost",
|
|
||||||
"created": "2023-08-27T13:32:11.704606963Z",
|
|
||||||
"updated": "2023-12-17T09:08:31.909723372Z",
|
|
||||||
"settings": {
|
|
||||||
"debug_info": false,
|
|
||||||
"reader_settings": {
|
|
||||||
"font": "serif",
|
|
||||||
"font_size": 3,
|
|
||||||
"line_height": 3
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
@ -1,125 +0,0 @@
|
|||||||
---
|
|
||||||
# SPDX-FileCopyrightText: © 2023 Olivier Meunier <olivier@neokraft.net>
|
|
||||||
#
|
|
||||||
# SPDX-License-Identifier: AGPL-3.0-only
|
|
||||||
|
|
||||||
authenticated:
|
|
||||||
responses:
|
|
||||||
"401":
|
|
||||||
description: |
|
|
||||||
Unauthorized. The request token found in the Authorization header is not valid.
|
|
||||||
content:
|
|
||||||
application/json:
|
|
||||||
schema:
|
|
||||||
$ref: "#/components/schemas/message"
|
|
||||||
"403":
|
|
||||||
description: |
|
|
||||||
Forbidden. The user doesn't have permission to fetch users for the specified,
|
|
||||||
but has other account permissions
|
|
||||||
content:
|
|
||||||
application/json:
|
|
||||||
schema:
|
|
||||||
$ref: "#/components/schemas/message"
|
|
||||||
|
|
||||||
paginated:
|
|
||||||
parameters:
|
|
||||||
- name: limit
|
|
||||||
in: query
|
|
||||||
description: Number of items per page
|
|
||||||
schema:
|
|
||||||
type: integer
|
|
||||||
- name: offset
|
|
||||||
in: query
|
|
||||||
description: Pagination offset
|
|
||||||
schema:
|
|
||||||
type: integer
|
|
||||||
|
|
||||||
responses:
|
|
||||||
'200':
|
|
||||||
headers:
|
|
||||||
Link:
|
|
||||||
description: Link to other pages in paginated results
|
|
||||||
schema:
|
|
||||||
type: array
|
|
||||||
items:
|
|
||||||
type: string
|
|
||||||
Current-Page:
|
|
||||||
description: Current page number
|
|
||||||
schema:
|
|
||||||
type: integer
|
|
||||||
Total-Count:
|
|
||||||
description: Total number of items
|
|
||||||
schema:
|
|
||||||
type: integer
|
|
||||||
Total-Pages:
|
|
||||||
description: Total number of pages
|
|
||||||
schema:
|
|
||||||
type: integer
|
|
||||||
|
|
||||||
created:
|
|
||||||
responses:
|
|
||||||
"201":
|
|
||||||
headers:
|
|
||||||
Location:
|
|
||||||
description: URL of the created resource
|
|
||||||
schema:
|
|
||||||
type: string
|
|
||||||
format: uri
|
|
||||||
content:
|
|
||||||
application/json:
|
|
||||||
schema:
|
|
||||||
$ref: "#/components/schemas/message"
|
|
||||||
|
|
||||||
deferred:
|
|
||||||
responses:
|
|
||||||
"202":
|
|
||||||
headers:
|
|
||||||
Location:
|
|
||||||
description: URL of the created resource
|
|
||||||
schema:
|
|
||||||
type: string
|
|
||||||
format: uri
|
|
||||||
content:
|
|
||||||
application/json:
|
|
||||||
schema:
|
|
||||||
$ref: "#/components/schemas/message"
|
|
||||||
|
|
||||||
validator:
|
|
||||||
responses:
|
|
||||||
"422":
|
|
||||||
description: |
|
|
||||||
This HTTP response is sent when the input data is not valid. It contains an object
|
|
||||||
with all the detected errors.
|
|
||||||
content:
|
|
||||||
application/json:
|
|
||||||
schema:
|
|
||||||
properties:
|
|
||||||
is_valid:
|
|
||||||
type: boolean
|
|
||||||
description: |
|
|
||||||
`true` if the input is valid
|
|
||||||
errors:
|
|
||||||
type: "[string]"
|
|
||||||
nullable: true
|
|
||||||
description: List of global input errors
|
|
||||||
fields:
|
|
||||||
type: object
|
|
||||||
description: |
|
|
||||||
All the fields, with and without errors
|
|
||||||
additionalProperties:
|
|
||||||
properties:
|
|
||||||
is_null:
|
|
||||||
type: boolean
|
|
||||||
description: |
|
|
||||||
`true` if the input value is null
|
|
||||||
is_bound:
|
|
||||||
type: boolean
|
|
||||||
description: |
|
|
||||||
`true` when the value is bound to the form
|
|
||||||
value:
|
|
||||||
type: any
|
|
||||||
description: Item's value; can be any type
|
|
||||||
errors:
|
|
||||||
type: "[string]"
|
|
||||||
nullable: true
|
|
||||||
description: List of errors for this field
|
|
||||||
@ -1,14 +0,0 @@
|
|||||||
---
|
|
||||||
# SPDX-FileCopyrightText: © 2023 Olivier Meunier <olivier@neokraft.net>
|
|
||||||
#
|
|
||||||
# SPDX-License-Identifier: AGPL-3.0-only
|
|
||||||
|
|
||||||
schemas:
|
|
||||||
message:
|
|
||||||
properties:
|
|
||||||
status:
|
|
||||||
type: integer
|
|
||||||
description: HTTP Status Code
|
|
||||||
message:
|
|
||||||
type: string
|
|
||||||
description: Information or error message
|
|
||||||
339
readeck-api.yaml
339
readeck-api.yaml
@ -1,339 +0,0 @@
|
|||||||
---
|
|
||||||
# SPDX-FileCopyrightText: © 2023 Olivier Meunier <olivier@neokraft.net>
|
|
||||||
#
|
|
||||||
# SPDX-License-Identifier: AGPL-3.0-only
|
|
||||||
|
|
||||||
openapi: 3.0.0
|
|
||||||
info:
|
|
||||||
version: 1.0.0
|
|
||||||
title: Readeck API
|
|
||||||
description: |
|
|
||||||
# Introduction
|
|
||||||
|
|
||||||
The Readeck API provides REST endpoints that can be used for any purpose, should it be a
|
|
||||||
mobile application, a script, you name it.
|
|
||||||
|
|
||||||
## API Endpoint
|
|
||||||
|
|
||||||
You can access this API on `__BASE_URI__`.
|
|
||||||
|
|
||||||
Most of your requests and responses are using JSON as the exchange format.
|
|
||||||
|
|
||||||
## Authentication
|
|
||||||
|
|
||||||
To use the API, you first need to [create an authentication token](../profile/tokens). You can
|
|
||||||
then use your new token using the `Bearer` HTTP authorization scheme.
|
|
||||||
|
|
||||||
For example, you first request will look like:
|
|
||||||
|
|
||||||
```sh
|
|
||||||
curl -H "Authorization: Bearer <TOKEN>" __BASE_URI__/bookmarks
|
|
||||||
```
|
|
||||||
|
|
||||||
Or, in NodeJS:
|
|
||||||
|
|
||||||
```js
|
|
||||||
fetch("__BASE_URI__/bookmarks", {
|
|
||||||
headers: {
|
|
||||||
"Authorization": "Bearer <TOKEN>",
|
|
||||||
},
|
|
||||||
})
|
|
||||||
```
|
|
||||||
|
|
||||||
## First time authentication
|
|
||||||
|
|
||||||
While you can create an authentication token from Readeck, you can also get one directly from
|
|
||||||
the API. This provides a mechanism to ask for user credentials and obtain a token for your app
|
|
||||||
only.
|
|
||||||
|
|
||||||
Please refer to [POST /auth](#post-/auth) for more information.
|
|
||||||
|
|
||||||
## Test the API
|
|
||||||
|
|
||||||
On this documentation, you can test every route.
|
|
||||||
|
|
||||||
If you don't provide an API token in [Authentication](#auth), you can still test all the routes
|
|
||||||
but note that the given curl examples only work with an API token.
|
|
||||||
|
|
||||||
|
|
||||||
servers:
|
|
||||||
- url: __BASE_URI__
|
|
||||||
|
|
||||||
components:
|
|
||||||
securitySchemes:
|
|
||||||
bearer:
|
|
||||||
type: http
|
|
||||||
scheme: Bearer
|
|
||||||
|
|
||||||
schemas:
|
|
||||||
$merge:
|
|
||||||
- "types.yaml#.schemas"
|
|
||||||
- "bookmarks/types.yaml#.schemas"
|
|
||||||
- "profile/types.yaml#.schemas"
|
|
||||||
|
|
||||||
security:
|
|
||||||
- bearer: []
|
|
||||||
|
|
||||||
tags:
|
|
||||||
- name: user profile
|
|
||||||
- name: bookmarks
|
|
||||||
- name: bookmark export
|
|
||||||
- name: bookmark sharing
|
|
||||||
- name: bookmark labels
|
|
||||||
- name: bookmark highlights
|
|
||||||
- name: bookmark collections
|
|
||||||
- name: bookmarks import
|
|
||||||
- name: dev tools
|
|
||||||
|
|
||||||
paths:
|
|
||||||
/auth:
|
|
||||||
post:
|
|
||||||
tags: [user profile]
|
|
||||||
$merge:
|
|
||||||
- "profile/routes.yaml#.auth"
|
|
||||||
|
|
||||||
/profile:
|
|
||||||
get:
|
|
||||||
tags: [user profile]
|
|
||||||
$merge:
|
|
||||||
- "traits.yaml#.authenticated"
|
|
||||||
- "profile/routes.yaml#.profile"
|
|
||||||
|
|
||||||
/bookmarks:
|
|
||||||
get:
|
|
||||||
tags: [bookmarks]
|
|
||||||
$merge:
|
|
||||||
- "traits.yaml#.authenticated"
|
|
||||||
- "traits.yaml#.paginated"
|
|
||||||
- "bookmarks/traits.yaml#.sortable"
|
|
||||||
- "bookmarks/routes.yaml#.list"
|
|
||||||
|
|
||||||
post:
|
|
||||||
tags: [bookmarks]
|
|
||||||
$merge:
|
|
||||||
- "traits.yaml#.authenticated"
|
|
||||||
- "traits.yaml#.validator"
|
|
||||||
- "traits.yaml#.deferred"
|
|
||||||
- "bookmarks/routes.yaml#.create"
|
|
||||||
|
|
||||||
/bookmarks/{id}:
|
|
||||||
$merge:
|
|
||||||
- "bookmarks/routes.yaml#.withBookmark"
|
|
||||||
|
|
||||||
get:
|
|
||||||
tags: [bookmarks]
|
|
||||||
$merge:
|
|
||||||
- "traits.yaml#.authenticated"
|
|
||||||
- "bookmarks/routes.yaml#.retrieve"
|
|
||||||
|
|
||||||
patch:
|
|
||||||
tags: [bookmarks]
|
|
||||||
$merge:
|
|
||||||
- "traits.yaml#.authenticated"
|
|
||||||
- "traits.yaml#.validator"
|
|
||||||
- "bookmarks/routes.yaml#.update"
|
|
||||||
|
|
||||||
delete:
|
|
||||||
tags: [bookmarks]
|
|
||||||
$merge:
|
|
||||||
- "traits.yaml#.authenticated"
|
|
||||||
- "bookmarks/routes.yaml#.delete"
|
|
||||||
|
|
||||||
/bookmarks/{id}/article:
|
|
||||||
$merge:
|
|
||||||
- "bookmarks/routes.yaml#.withBookmark"
|
|
||||||
|
|
||||||
get:
|
|
||||||
tags: [bookmark export]
|
|
||||||
$merge:
|
|
||||||
- "traits.yaml#.authenticated"
|
|
||||||
- "bookmarks/routes.yaml#.article"
|
|
||||||
|
|
||||||
/bookmarks/{id}/article.{format}:
|
|
||||||
$merge:
|
|
||||||
- "bookmarks/routes.yaml#.withBookmark"
|
|
||||||
|
|
||||||
get:
|
|
||||||
tags: [bookmark export]
|
|
||||||
$merge:
|
|
||||||
- "traits.yaml#.authenticated"
|
|
||||||
- "bookmarks/routes.yaml#.export"
|
|
||||||
|
|
||||||
/bookmarks/{id}/share/link:
|
|
||||||
$merge:
|
|
||||||
- "bookmarks/routes.yaml#.withBookmark"
|
|
||||||
|
|
||||||
get:
|
|
||||||
tags: [bookmark sharing]
|
|
||||||
$merge:
|
|
||||||
- "traits.yaml#.authenticated"
|
|
||||||
- "bookmarks/routes.yaml#.shareLink"
|
|
||||||
|
|
||||||
/bookmarks/{id}/share/email:
|
|
||||||
$merge:
|
|
||||||
- "bookmarks/routes.yaml#.withBookmark"
|
|
||||||
|
|
||||||
post:
|
|
||||||
tags: [bookmark sharing]
|
|
||||||
$merge:
|
|
||||||
- "traits.yaml#.authenticated"
|
|
||||||
- "bookmarks/routes.yaml#.shareEmail"
|
|
||||||
|
|
||||||
/bookmarks/labels:
|
|
||||||
get:
|
|
||||||
tags: [bookmark labels]
|
|
||||||
$merge:
|
|
||||||
- "traits.yaml#.authenticated"
|
|
||||||
- "bookmarks/routes.yaml#.labels"
|
|
||||||
|
|
||||||
/bookmarks/labels/{name}:
|
|
||||||
$merge:
|
|
||||||
- "bookmarks/routes.yaml#.withLabel"
|
|
||||||
|
|
||||||
get:
|
|
||||||
tags: [bookmark labels]
|
|
||||||
$merge:
|
|
||||||
- "traits.yaml#.authenticated"
|
|
||||||
- "bookmarks/routes.yaml#.labelInfo"
|
|
||||||
|
|
||||||
patch:
|
|
||||||
tags: [bookmark labels]
|
|
||||||
$merge:
|
|
||||||
- "traits.yaml#.authenticated"
|
|
||||||
- "traits.yaml#.validator"
|
|
||||||
- "bookmarks/routes.yaml#.labelUpdate"
|
|
||||||
|
|
||||||
delete:
|
|
||||||
tags: [bookmark labels]
|
|
||||||
$merge:
|
|
||||||
- "traits.yaml#.authenticated"
|
|
||||||
- "bookmarks/routes.yaml#.labelDelete"
|
|
||||||
|
|
||||||
/bookmarks/annotations:
|
|
||||||
get:
|
|
||||||
tags: [bookmark highlights]
|
|
||||||
$merge:
|
|
||||||
- "traits.yaml#.authenticated"
|
|
||||||
- "traits.yaml#.paginated"
|
|
||||||
- "bookmarks/routes.yaml#.annotationList"
|
|
||||||
|
|
||||||
/bookmarks/{id}/annotations:
|
|
||||||
$merge:
|
|
||||||
- "bookmarks/routes.yaml#.withBookmark"
|
|
||||||
|
|
||||||
get:
|
|
||||||
tags: [bookmark highlights]
|
|
||||||
$merge:
|
|
||||||
- "traits.yaml#.authenticated"
|
|
||||||
- "bookmarks/routes.yaml#.bookmarkAnnotationList"
|
|
||||||
|
|
||||||
post:
|
|
||||||
tags: [bookmark highlights]
|
|
||||||
$merge:
|
|
||||||
- "traits.yaml#.authenticated"
|
|
||||||
- "traits.yaml#.validator"
|
|
||||||
- "traits.yaml#.created"
|
|
||||||
- "bookmarks/routes.yaml#.bookmarkAnnotationCreate"
|
|
||||||
|
|
||||||
/bookmarks/{id}/annotations/{annotation_id}:
|
|
||||||
$merge:
|
|
||||||
- "bookmarks/routes.yaml#.withBookmark"
|
|
||||||
|
|
||||||
patch:
|
|
||||||
tags: [bookmark highlights]
|
|
||||||
$merge:
|
|
||||||
- "traits.yaml#.authenticated"
|
|
||||||
- "traits.yaml#.validator"
|
|
||||||
- "bookmarks/routes.yaml#.withAnnotation"
|
|
||||||
- "bookmarks/routes.yaml#.bookmarkAnnotationUpdate"
|
|
||||||
|
|
||||||
delete:
|
|
||||||
tags: [bookmark highlights]
|
|
||||||
$merge:
|
|
||||||
- "traits.yaml#.authenticated"
|
|
||||||
- "bookmarks/routes.yaml#.withAnnotation"
|
|
||||||
- "bookmarks/routes.yaml#.bookmarkAnnotationDelete"
|
|
||||||
|
|
||||||
/bookmarks/collections:
|
|
||||||
get:
|
|
||||||
tags: [bookmark collections]
|
|
||||||
$merge:
|
|
||||||
- "traits.yaml#.authenticated"
|
|
||||||
- "traits.yaml#.paginated"
|
|
||||||
- "bookmarks/routes.yaml#.collectionList"
|
|
||||||
|
|
||||||
post:
|
|
||||||
tags: [bookmark collections]
|
|
||||||
$merge:
|
|
||||||
- "traits.yaml#.authenticated"
|
|
||||||
- "traits.yaml#.created"
|
|
||||||
- "bookmarks/routes.yaml#.collectionCreate"
|
|
||||||
|
|
||||||
/bookmarks/collections/{id}:
|
|
||||||
$merge:
|
|
||||||
- "bookmarks/routes.yaml#.withCollection"
|
|
||||||
|
|
||||||
get:
|
|
||||||
tags: [bookmark collections]
|
|
||||||
$merge:
|
|
||||||
- "traits.yaml#.authenticated"
|
|
||||||
- "bookmarks/routes.yaml#.collectionInfo"
|
|
||||||
|
|
||||||
patch:
|
|
||||||
tags: [bookmark collections]
|
|
||||||
$merge:
|
|
||||||
- "traits.yaml#.authenticated"
|
|
||||||
- "bookmarks/routes.yaml#.collectionUpdate"
|
|
||||||
|
|
||||||
delete:
|
|
||||||
tags: [bookmark collections]
|
|
||||||
$merge:
|
|
||||||
- "traits.yaml#.authenticated"
|
|
||||||
- "bookmarks/routes.yaml#.collectionDelete"
|
|
||||||
|
|
||||||
/bookmarks/import/text:
|
|
||||||
post:
|
|
||||||
tags: [bookmarks import]
|
|
||||||
$merge:
|
|
||||||
- "traits.yaml#.authenticated"
|
|
||||||
- "traits.yaml#.validator"
|
|
||||||
- "traits.yaml#.deferred"
|
|
||||||
- "bookmarks/routes.yaml#.importMultipartGeneric"
|
|
||||||
- "bookmarks/routes.yaml#.importTextFile"
|
|
||||||
|
|
||||||
/bookmarks/import/browser:
|
|
||||||
post:
|
|
||||||
tags: [bookmarks import]
|
|
||||||
$merge:
|
|
||||||
- "traits.yaml#.authenticated"
|
|
||||||
- "traits.yaml#.validator"
|
|
||||||
- "traits.yaml#.deferred"
|
|
||||||
- "bookmarks/routes.yaml#.importMultipartGeneric"
|
|
||||||
- "bookmarks/routes.yaml#.importBrowserBookmarks"
|
|
||||||
|
|
||||||
/bookmarks/import/pocket-file:
|
|
||||||
post:
|
|
||||||
tags: [bookmarks import]
|
|
||||||
$merge:
|
|
||||||
- "traits.yaml#.authenticated"
|
|
||||||
- "traits.yaml#.validator"
|
|
||||||
- "traits.yaml#.deferred"
|
|
||||||
- "bookmarks/routes.yaml#.importMultipartGeneric"
|
|
||||||
- "bookmarks/routes.yaml#.importPocket"
|
|
||||||
|
|
||||||
/bookmarks/import/wallabag:
|
|
||||||
post:
|
|
||||||
tags: [bookmarks import]
|
|
||||||
$merge:
|
|
||||||
- "traits.yaml#.authenticated"
|
|
||||||
- "traits.yaml#.validator"
|
|
||||||
- "traits.yaml#.deferred"
|
|
||||||
- "bookmarks/routes.yaml#.importWallabag"
|
|
||||||
|
|
||||||
|
|
||||||
/cookbook/extract:
|
|
||||||
get:
|
|
||||||
tags: [dev tools]
|
|
||||||
$merge:
|
|
||||||
- "traits.yaml#.authenticated"
|
|
||||||
- "cookbook/routes.yaml#.extract"
|
|
||||||
@ -1,339 +0,0 @@
|
|||||||
---
|
|
||||||
# SPDX-FileCopyrightText: © 2023 Olivier Meunier <olivier@neokraft.net>
|
|
||||||
#
|
|
||||||
# SPDX-License-Identifier: AGPL-3.0-only
|
|
||||||
|
|
||||||
openapi: 3.0.0
|
|
||||||
info:
|
|
||||||
version: 1.0.0
|
|
||||||
title: Readeck API
|
|
||||||
description: |
|
|
||||||
# Introduction
|
|
||||||
|
|
||||||
The Readeck API provides REST endpoints that can be used for any purpose, should it be a
|
|
||||||
mobile application, a script, you name it.
|
|
||||||
|
|
||||||
## API Endpoint
|
|
||||||
|
|
||||||
You can access this API on `__BASE_URI__`.
|
|
||||||
|
|
||||||
Most of your requests and responses are using JSON as the exchange format.
|
|
||||||
|
|
||||||
## Authentication
|
|
||||||
|
|
||||||
To use the API, you first need to [create an authentication token](../profile/tokens). You can
|
|
||||||
then use your new token using the `Bearer` HTTP authorization scheme.
|
|
||||||
|
|
||||||
For example, you first request will look like:
|
|
||||||
|
|
||||||
```sh
|
|
||||||
curl -H "Authorization: Bearer <TOKEN>" __BASE_URI__/bookmarks
|
|
||||||
```
|
|
||||||
|
|
||||||
Or, in NodeJS:
|
|
||||||
|
|
||||||
```js
|
|
||||||
fetch("__BASE_URI__/bookmarks", {
|
|
||||||
headers: {
|
|
||||||
"Authorization": "Bearer <TOKEN>",
|
|
||||||
},
|
|
||||||
})
|
|
||||||
```
|
|
||||||
|
|
||||||
## First time authentication
|
|
||||||
|
|
||||||
While you can create an authentication token from Readeck, you can also get one directly from
|
|
||||||
the API. This provides a mechanism to ask for user credentials and obtain a token for your app
|
|
||||||
only.
|
|
||||||
|
|
||||||
Please refer to [POST /auth](#post-/auth) for more information.
|
|
||||||
|
|
||||||
## Test the API
|
|
||||||
|
|
||||||
On this documentation, you can test every route.
|
|
||||||
|
|
||||||
If you don't provide an API token in [Authentication](#auth), you can still test all the routes
|
|
||||||
but note that the given curl examples only work with an API token.
|
|
||||||
|
|
||||||
|
|
||||||
servers:
|
|
||||||
- url: __BASE_URI__
|
|
||||||
|
|
||||||
components:
|
|
||||||
securitySchemes:
|
|
||||||
bearer:
|
|
||||||
type: http
|
|
||||||
scheme: Bearer
|
|
||||||
|
|
||||||
schemas:
|
|
||||||
$merge:
|
|
||||||
- "types.yaml#.schemas"
|
|
||||||
- "bookmarks/types.yaml#.schemas"
|
|
||||||
- "profile/types.yaml#.schemas"
|
|
||||||
|
|
||||||
security:
|
|
||||||
- bearer: []
|
|
||||||
|
|
||||||
tags:
|
|
||||||
- name: user profile
|
|
||||||
- name: bookmarks
|
|
||||||
- name: bookmark export
|
|
||||||
- name: bookmark sharing
|
|
||||||
- name: bookmark labels
|
|
||||||
- name: bookmark highlights
|
|
||||||
- name: bookmark collections
|
|
||||||
- name: bookmarks import
|
|
||||||
- name: dev tools
|
|
||||||
|
|
||||||
paths:
|
|
||||||
/auth:
|
|
||||||
post:
|
|
||||||
tags: [user profile]
|
|
||||||
$merge:
|
|
||||||
- "profile/routes.yaml#.auth"
|
|
||||||
|
|
||||||
/profile:
|
|
||||||
get:
|
|
||||||
tags: [user profile]
|
|
||||||
$merge:
|
|
||||||
- "traits.yaml#.authenticated"
|
|
||||||
- "profile/routes.yaml#.profile"
|
|
||||||
|
|
||||||
/bookmarks:
|
|
||||||
get:
|
|
||||||
tags: [bookmarks]
|
|
||||||
$merge:
|
|
||||||
- "traits.yaml#.authenticated"
|
|
||||||
- "traits.yaml#.paginated"
|
|
||||||
- "bookmarks/traits.yaml#.sortable"
|
|
||||||
- "bookmarks/routes.yaml#.list"
|
|
||||||
|
|
||||||
post:
|
|
||||||
tags: [bookmarks]
|
|
||||||
$merge:
|
|
||||||
- "traits.yaml#.authenticated"
|
|
||||||
- "traits.yaml#.validator"
|
|
||||||
- "traits.yaml#.deferred"
|
|
||||||
- "bookmarks/routes.yaml#.create"
|
|
||||||
|
|
||||||
/bookmarks/{id}:
|
|
||||||
$merge:
|
|
||||||
- "bookmarks/routes.yaml#.withBookmark"
|
|
||||||
|
|
||||||
get:
|
|
||||||
tags: [bookmarks]
|
|
||||||
$merge:
|
|
||||||
- "traits.yaml#.authenticated"
|
|
||||||
- "bookmarks/routes.yaml#.retrieve"
|
|
||||||
|
|
||||||
patch:
|
|
||||||
tags: [bookmarks]
|
|
||||||
$merge:
|
|
||||||
- "traits.yaml#.authenticated"
|
|
||||||
- "traits.yaml#.validator"
|
|
||||||
- "bookmarks/routes.yaml#.update"
|
|
||||||
|
|
||||||
delete:
|
|
||||||
tags: [bookmarks]
|
|
||||||
$merge:
|
|
||||||
- "traits.yaml#.authenticated"
|
|
||||||
- "bookmarks/routes.yaml#.delete"
|
|
||||||
|
|
||||||
/bookmarks/{id}/article:
|
|
||||||
$merge:
|
|
||||||
- "bookmarks/routes.yaml#.withBookmark"
|
|
||||||
|
|
||||||
get:
|
|
||||||
tags: [bookmark export]
|
|
||||||
$merge:
|
|
||||||
- "traits.yaml#.authenticated"
|
|
||||||
- "bookmarks/routes.yaml#.article"
|
|
||||||
|
|
||||||
/bookmarks/{id}/article.{format}:
|
|
||||||
$merge:
|
|
||||||
- "bookmarks/routes.yaml#.withBookmark"
|
|
||||||
|
|
||||||
get:
|
|
||||||
tags: [bookmark export]
|
|
||||||
$merge:
|
|
||||||
- "traits.yaml#.authenticated"
|
|
||||||
- "bookmarks/routes.yaml#.export"
|
|
||||||
|
|
||||||
/bookmarks/{id}/share/link:
|
|
||||||
$merge:
|
|
||||||
- "bookmarks/routes.yaml#.withBookmark"
|
|
||||||
|
|
||||||
get:
|
|
||||||
tags: [bookmark sharing]
|
|
||||||
$merge:
|
|
||||||
- "traits.yaml#.authenticated"
|
|
||||||
- "bookmarks/routes.yaml#.shareLink"
|
|
||||||
|
|
||||||
/bookmarks/{id}/share/email:
|
|
||||||
$merge:
|
|
||||||
- "bookmarks/routes.yaml#.withBookmark"
|
|
||||||
|
|
||||||
post:
|
|
||||||
tags: [bookmark sharing]
|
|
||||||
$merge:
|
|
||||||
- "traits.yaml#.authenticated"
|
|
||||||
- "bookmarks/routes.yaml#.shareEmail"
|
|
||||||
|
|
||||||
/bookmarks/labels:
|
|
||||||
get:
|
|
||||||
tags: [bookmark labels]
|
|
||||||
$merge:
|
|
||||||
- "traits.yaml#.authenticated"
|
|
||||||
- "bookmarks/routes.yaml#.labels"
|
|
||||||
|
|
||||||
/bookmarks/labels/{name}:
|
|
||||||
$merge:
|
|
||||||
- "bookmarks/routes.yaml#.withLabel"
|
|
||||||
|
|
||||||
get:
|
|
||||||
tags: [bookmark labels]
|
|
||||||
$merge:
|
|
||||||
- "traits.yaml#.authenticated"
|
|
||||||
- "bookmarks/routes.yaml#.labelInfo"
|
|
||||||
|
|
||||||
patch:
|
|
||||||
tags: [bookmark labels]
|
|
||||||
$merge:
|
|
||||||
- "traits.yaml#.authenticated"
|
|
||||||
- "traits.yaml#.validator"
|
|
||||||
- "bookmarks/routes.yaml#.labelUpdate"
|
|
||||||
|
|
||||||
delete:
|
|
||||||
tags: [bookmark labels]
|
|
||||||
$merge:
|
|
||||||
- "traits.yaml#.authenticated"
|
|
||||||
- "bookmarks/routes.yaml#.labelDelete"
|
|
||||||
|
|
||||||
/bookmarks/annotations:
|
|
||||||
get:
|
|
||||||
tags: [bookmark highlights]
|
|
||||||
$merge:
|
|
||||||
- "traits.yaml#.authenticated"
|
|
||||||
- "traits.yaml#.paginated"
|
|
||||||
- "bookmarks/routes.yaml#.annotationList"
|
|
||||||
|
|
||||||
/bookmarks/{id}/annotations:
|
|
||||||
$merge:
|
|
||||||
- "bookmarks/routes.yaml#.withBookmark"
|
|
||||||
|
|
||||||
get:
|
|
||||||
tags: [bookmark highlights]
|
|
||||||
$merge:
|
|
||||||
- "traits.yaml#.authenticated"
|
|
||||||
- "bookmarks/routes.yaml#.bookmarkAnnotationList"
|
|
||||||
|
|
||||||
post:
|
|
||||||
tags: [bookmark highlights]
|
|
||||||
$merge:
|
|
||||||
- "traits.yaml#.authenticated"
|
|
||||||
- "traits.yaml#.validator"
|
|
||||||
- "traits.yaml#.created"
|
|
||||||
- "bookmarks/routes.yaml#.bookmarkAnnotationCreate"
|
|
||||||
|
|
||||||
/bookmarks/{id}/annotations/{annotation_id}:
|
|
||||||
$merge:
|
|
||||||
- "bookmarks/routes.yaml#.withBookmark"
|
|
||||||
|
|
||||||
patch:
|
|
||||||
tags: [bookmark highlights]
|
|
||||||
$merge:
|
|
||||||
- "traits.yaml#.authenticated"
|
|
||||||
- "traits.yaml#.validator"
|
|
||||||
- "bookmarks/routes.yaml#.withAnnotation"
|
|
||||||
- "bookmarks/routes.yaml#.bookmarkAnnotationUpdate"
|
|
||||||
|
|
||||||
delete:
|
|
||||||
tags: [bookmark highlights]
|
|
||||||
$merge:
|
|
||||||
- "traits.yaml#.authenticated"
|
|
||||||
- "bookmarks/routes.yaml#.withAnnotation"
|
|
||||||
- "bookmarks/routes.yaml#.bookmarkAnnotationDelete"
|
|
||||||
|
|
||||||
/bookmarks/collections:
|
|
||||||
get:
|
|
||||||
tags: [bookmark collections]
|
|
||||||
$merge:
|
|
||||||
- "traits.yaml#.authenticated"
|
|
||||||
- "traits.yaml#.paginated"
|
|
||||||
- "bookmarks/routes.yaml#.collectionList"
|
|
||||||
|
|
||||||
post:
|
|
||||||
tags: [bookmark collections]
|
|
||||||
$merge:
|
|
||||||
- "traits.yaml#.authenticated"
|
|
||||||
- "traits.yaml#.created"
|
|
||||||
- "bookmarks/routes.yaml#.collectionCreate"
|
|
||||||
|
|
||||||
/bookmarks/collections/{id}:
|
|
||||||
$merge:
|
|
||||||
- "bookmarks/routes.yaml#.withCollection"
|
|
||||||
|
|
||||||
get:
|
|
||||||
tags: [bookmark collections]
|
|
||||||
$merge:
|
|
||||||
- "traits.yaml#.authenticated"
|
|
||||||
- "bookmarks/routes.yaml#.collectionInfo"
|
|
||||||
|
|
||||||
patch:
|
|
||||||
tags: [bookmark collections]
|
|
||||||
$merge:
|
|
||||||
- "traits.yaml#.authenticated"
|
|
||||||
- "bookmarks/routes.yaml#.collectionUpdate"
|
|
||||||
|
|
||||||
delete:
|
|
||||||
tags: [bookmark collections]
|
|
||||||
$merge:
|
|
||||||
- "traits.yaml#.authenticated"
|
|
||||||
- "bookmarks/routes.yaml#.collectionDelete"
|
|
||||||
|
|
||||||
/bookmarks/import/text:
|
|
||||||
post:
|
|
||||||
tags: [bookmarks import]
|
|
||||||
$merge:
|
|
||||||
- "traits.yaml#.authenticated"
|
|
||||||
- "traits.yaml#.validator"
|
|
||||||
- "traits.yaml#.deferred"
|
|
||||||
- "bookmarks/routes.yaml#.importMultipartGeneric"
|
|
||||||
- "bookmarks/routes.yaml#.importTextFile"
|
|
||||||
|
|
||||||
/bookmarks/import/browser:
|
|
||||||
post:
|
|
||||||
tags: [bookmarks import]
|
|
||||||
$merge:
|
|
||||||
- "traits.yaml#.authenticated"
|
|
||||||
- "traits.yaml#.validator"
|
|
||||||
- "traits.yaml#.deferred"
|
|
||||||
- "bookmarks/routes.yaml#.importMultipartGeneric"
|
|
||||||
- "bookmarks/routes.yaml#.importBrowserBookmarks"
|
|
||||||
|
|
||||||
/bookmarks/import/pocket-file:
|
|
||||||
post:
|
|
||||||
tags: [bookmarks import]
|
|
||||||
$merge:
|
|
||||||
- "traits.yaml#.authenticated"
|
|
||||||
- "traits.yaml#.validator"
|
|
||||||
- "traits.yaml#.deferred"
|
|
||||||
- "bookmarks/routes.yaml#.importMultipartGeneric"
|
|
||||||
- "bookmarks/routes.yaml#.importPocket"
|
|
||||||
|
|
||||||
/bookmarks/import/wallabag:
|
|
||||||
post:
|
|
||||||
tags: [bookmarks import]
|
|
||||||
$merge:
|
|
||||||
- "traits.yaml#.authenticated"
|
|
||||||
- "traits.yaml#.validator"
|
|
||||||
- "traits.yaml#.deferred"
|
|
||||||
- "bookmarks/routes.yaml#.importWallabag"
|
|
||||||
|
|
||||||
|
|
||||||
/cookbook/extract:
|
|
||||||
get:
|
|
||||||
tags: [dev tools]
|
|
||||||
$merge:
|
|
||||||
- "traits.yaml#.authenticated"
|
|
||||||
- "cookbook/routes.yaml#.extract"
|
|
||||||
@ -1,563 +0,0 @@
|
|||||||
---
|
|
||||||
# SPDX-FileCopyrightText: © 2023 Olivier Meunier <olivier@neokraft.net>
|
|
||||||
#
|
|
||||||
# SPDX-License-Identifier: AGPL-3.0-only
|
|
||||||
|
|
||||||
withBookmark:
|
|
||||||
parameters:
|
|
||||||
- name: id
|
|
||||||
in: path
|
|
||||||
required: true
|
|
||||||
description: Bookmark ID
|
|
||||||
schema:
|
|
||||||
type: string
|
|
||||||
format: short-uid
|
|
||||||
|
|
||||||
withLabel:
|
|
||||||
parameters:
|
|
||||||
- name: name
|
|
||||||
in: path
|
|
||||||
required: true
|
|
||||||
description: Label
|
|
||||||
schema:
|
|
||||||
type: string
|
|
||||||
|
|
||||||
withAnnotation:
|
|
||||||
parameters:
|
|
||||||
- name: annotation_id
|
|
||||||
in: path
|
|
||||||
required: true
|
|
||||||
description: Highlight ID
|
|
||||||
schema:
|
|
||||||
type: string
|
|
||||||
format: short-uid
|
|
||||||
|
|
||||||
withCollection:
|
|
||||||
parameters:
|
|
||||||
- name: id
|
|
||||||
in: path
|
|
||||||
required: true
|
|
||||||
description: Collection ID
|
|
||||||
schema:
|
|
||||||
type: string
|
|
||||||
format: short-uid
|
|
||||||
|
|
||||||
# GET /bookmarks
|
|
||||||
list:
|
|
||||||
summary: Bookmark List
|
|
||||||
description: |
|
|
||||||
This route returns a paginated bookmark list.
|
|
||||||
|
|
||||||
parameters:
|
|
||||||
- name: search
|
|
||||||
in: query
|
|
||||||
description: A full text search string
|
|
||||||
schema:
|
|
||||||
type: string
|
|
||||||
- name: title
|
|
||||||
in: query
|
|
||||||
description: Bookmark title
|
|
||||||
schema:
|
|
||||||
type: string
|
|
||||||
- name: author
|
|
||||||
in: query
|
|
||||||
description: Author's name
|
|
||||||
schema:
|
|
||||||
type: string
|
|
||||||
- name: site
|
|
||||||
in: query
|
|
||||||
description: Bookmark site name or domain
|
|
||||||
schema:
|
|
||||||
type: string
|
|
||||||
- name: type
|
|
||||||
in: query
|
|
||||||
description: Bookmark type
|
|
||||||
schema:
|
|
||||||
type: array
|
|
||||||
items:
|
|
||||||
type: string
|
|
||||||
enum: [article, photo, video]
|
|
||||||
- name: labels
|
|
||||||
in: query
|
|
||||||
description: One or several labels
|
|
||||||
schema:
|
|
||||||
type: string
|
|
||||||
- name: is_loaded
|
|
||||||
in: query
|
|
||||||
description: Filter by loaded state
|
|
||||||
schema:
|
|
||||||
type: boolean
|
|
||||||
- name: has_errors
|
|
||||||
in: query
|
|
||||||
description: Filter bookmarks with or without errors
|
|
||||||
schema:
|
|
||||||
type: boolean
|
|
||||||
- name: has_labels
|
|
||||||
in: query
|
|
||||||
description: Filter bookmarks with or without labels
|
|
||||||
schema:
|
|
||||||
type: boolean
|
|
||||||
- name: is_marked
|
|
||||||
in: query
|
|
||||||
description: Filter by marked (favorite) status
|
|
||||||
schema:
|
|
||||||
type: boolean
|
|
||||||
- name: is_archived
|
|
||||||
in: query
|
|
||||||
description: Filter by archived status
|
|
||||||
schema:
|
|
||||||
type: boolean
|
|
||||||
- name: range_start
|
|
||||||
in: query
|
|
||||||
schema:
|
|
||||||
type: string
|
|
||||||
- name: range_end
|
|
||||||
in: query
|
|
||||||
schema:
|
|
||||||
type: string
|
|
||||||
- name: read_status
|
|
||||||
in: query
|
|
||||||
description: Read progress status
|
|
||||||
schema:
|
|
||||||
type: array
|
|
||||||
items:
|
|
||||||
type: string
|
|
||||||
enum: [unread, reading, read]
|
|
||||||
- name: updated_since
|
|
||||||
in: query
|
|
||||||
description: Retrieve bookmarks created after this date
|
|
||||||
schema:
|
|
||||||
type: string
|
|
||||||
format: date-time
|
|
||||||
- name: id
|
|
||||||
in: query
|
|
||||||
description: One or more bookmark ID
|
|
||||||
schema:
|
|
||||||
type: string
|
|
||||||
- name: collection
|
|
||||||
in: query
|
|
||||||
description: A collection ID
|
|
||||||
schema:
|
|
||||||
type: string
|
|
||||||
|
|
||||||
responses:
|
|
||||||
'200':
|
|
||||||
description: List of bookmark items
|
|
||||||
content:
|
|
||||||
application/json:
|
|
||||||
schema:
|
|
||||||
type: array
|
|
||||||
items:
|
|
||||||
$ref: "#/components/schemas/bookmarkSummary"
|
|
||||||
|
|
||||||
# POST /bookmarks
|
|
||||||
create:
|
|
||||||
summary: Bookmark Create
|
|
||||||
description: Creates a new bookmark
|
|
||||||
|
|
||||||
requestBody:
|
|
||||||
content:
|
|
||||||
application/json:
|
|
||||||
schema:
|
|
||||||
$ref: "#/components/schemas/bookmarkCreate"
|
|
||||||
|
|
||||||
responses:
|
|
||||||
"202":
|
|
||||||
headers:
|
|
||||||
Bookmark-Id:
|
|
||||||
schema:
|
|
||||||
type: string
|
|
||||||
description: ID of the created bookmark
|
|
||||||
|
|
||||||
# GET /bookmarks/{id}
|
|
||||||
retrieve:
|
|
||||||
summary: Bookmark Details
|
|
||||||
description: Retrieves a saved bookmark
|
|
||||||
|
|
||||||
responses:
|
|
||||||
"200":
|
|
||||||
description: Bookmark details
|
|
||||||
content:
|
|
||||||
application/json:
|
|
||||||
schema:
|
|
||||||
$ref: "#/components/schemas/bookmarkInfo"
|
|
||||||
|
|
||||||
# PATCH /bookmarks/{id}
|
|
||||||
update:
|
|
||||||
summary: Bookmark Update
|
|
||||||
description: |
|
|
||||||
This route updates some bookmark's properties. Every input value is optional.
|
|
||||||
Upon success, it returns a mapping of changed values.
|
|
||||||
|
|
||||||
requestBody:
|
|
||||||
content:
|
|
||||||
application/json:
|
|
||||||
schema:
|
|
||||||
$ref: "#/components/schemas/bookmarkUpdate"
|
|
||||||
|
|
||||||
responses:
|
|
||||||
"200":
|
|
||||||
description: Bookmark updated
|
|
||||||
content:
|
|
||||||
application/json:
|
|
||||||
schema:
|
|
||||||
$ref: "#/components/schemas/bookmarkUpdated"
|
|
||||||
|
|
||||||
# DELETE /bookmarks/{id}
|
|
||||||
delete:
|
|
||||||
summary: Bookmark Delete
|
|
||||||
description: Deletes a saved bookmark
|
|
||||||
|
|
||||||
responses:
|
|
||||||
"204":
|
|
||||||
description: The bookmark was successfuly deleted.
|
|
||||||
|
|
||||||
# GET /bookmarks/{id}/article
|
|
||||||
article:
|
|
||||||
summary: Bookmark Article
|
|
||||||
description: |
|
|
||||||
This route returns the bookmark's article if it exists.
|
|
||||||
|
|
||||||
responses:
|
|
||||||
"200":
|
|
||||||
description: |
|
|
||||||
A `text/html` response, containing the article body.
|
|
||||||
Please note that it's only the fragment and not a full HTML document.
|
|
||||||
content:
|
|
||||||
text/html:
|
|
||||||
schema:
|
|
||||||
type: string
|
|
||||||
|
|
||||||
# GET /bookmarks/{id}/article.{format}
|
|
||||||
export:
|
|
||||||
summary: Bookmark Export
|
|
||||||
description: This route exports a bookmark to another format.
|
|
||||||
|
|
||||||
parameters:
|
|
||||||
- name: format
|
|
||||||
in: path
|
|
||||||
required: true
|
|
||||||
description: Export format
|
|
||||||
schema:
|
|
||||||
type: string
|
|
||||||
enum: [epub, md]
|
|
||||||
|
|
||||||
responses:
|
|
||||||
"200":
|
|
||||||
content:
|
|
||||||
application/epub+zip:
|
|
||||||
schema:
|
|
||||||
type: string
|
|
||||||
format: binary
|
|
||||||
text/markdown:
|
|
||||||
schema:
|
|
||||||
type: string
|
|
||||||
|
|
||||||
# GET /bookmarks/{id}/share/link
|
|
||||||
shareLink:
|
|
||||||
summary: Share by link
|
|
||||||
description: This route produces a publicly accessible link to share a bookmark.
|
|
||||||
|
|
||||||
responses:
|
|
||||||
"200":
|
|
||||||
description: Public link information
|
|
||||||
content:
|
|
||||||
application/json:
|
|
||||||
schema:
|
|
||||||
$ref: "#/components/schemas/bookmarkShareLink"
|
|
||||||
|
|
||||||
# POST /bookmarks/{id}/share/email
|
|
||||||
shareEmail:
|
|
||||||
summary: Share by email
|
|
||||||
description: This route sends a bookmark to an email address.
|
|
||||||
|
|
||||||
requestBody:
|
|
||||||
content:
|
|
||||||
application/json:
|
|
||||||
schema:
|
|
||||||
$ref: "#/components/schemas/bookmarkShareEmail"
|
|
||||||
|
|
||||||
responses:
|
|
||||||
"200":
|
|
||||||
description: Message sent
|
|
||||||
content:
|
|
||||||
application/json:
|
|
||||||
schema:
|
|
||||||
$ref: "#/components/schemas/message"
|
|
||||||
|
|
||||||
# GET /bookmarks/labels
|
|
||||||
labels:
|
|
||||||
summary: Label List
|
|
||||||
description: |
|
|
||||||
This route returns all the labels associated to a bookmark for the current user.
|
|
||||||
|
|
||||||
responses:
|
|
||||||
"200":
|
|
||||||
description: Label list
|
|
||||||
content:
|
|
||||||
application/json:
|
|
||||||
schema:
|
|
||||||
type: array
|
|
||||||
items:
|
|
||||||
$ref: "#/components/schemas/labelInfo"
|
|
||||||
|
|
||||||
# GET /bookmarks/labels/{name}
|
|
||||||
labelInfo:
|
|
||||||
summary: Label Info
|
|
||||||
description:
|
|
||||||
This route returns information about a given bookmark label.
|
|
||||||
|
|
||||||
responses:
|
|
||||||
"200":
|
|
||||||
description: Label information
|
|
||||||
content:
|
|
||||||
application/json:
|
|
||||||
schema:
|
|
||||||
type: array
|
|
||||||
items:
|
|
||||||
$ref: "#/components/schemas/labelInfo"
|
|
||||||
|
|
||||||
# PATCH /bookmarks/labels/{name}
|
|
||||||
labelUpdate:
|
|
||||||
summary: Label Update
|
|
||||||
description: |
|
|
||||||
This route renames a label.
|
|
||||||
|
|
||||||
requestBody:
|
|
||||||
content:
|
|
||||||
application/json:
|
|
||||||
schema:
|
|
||||||
$ref: "#/components/schemas/labelUpdate"
|
|
||||||
|
|
||||||
responses:
|
|
||||||
"200":
|
|
||||||
description: Label renamed
|
|
||||||
|
|
||||||
# DELETE /bookmarks/labels/{name}
|
|
||||||
labelDelete:
|
|
||||||
summary: Label Delete
|
|
||||||
description: |
|
|
||||||
This route remove a label from all associated bookmarks.
|
|
||||||
|
|
||||||
Please note that it does not remove the bookmarks themselves.
|
|
||||||
|
|
||||||
responses:
|
|
||||||
"204":
|
|
||||||
description: Label removed
|
|
||||||
|
|
||||||
# GET /bookmarks/annotations
|
|
||||||
annotationList:
|
|
||||||
summary: Highlight List
|
|
||||||
description: |
|
|
||||||
This route returns all the highlights created by the current user.
|
|
||||||
|
|
||||||
responses:
|
|
||||||
"200":
|
|
||||||
description: Highlight list
|
|
||||||
content:
|
|
||||||
application/json:
|
|
||||||
schema:
|
|
||||||
type: array
|
|
||||||
items:
|
|
||||||
$ref: "#/components/schemas/annotationSummary"
|
|
||||||
|
|
||||||
# GET /bookmarks/{id}annotations
|
|
||||||
bookmarkAnnotationList:
|
|
||||||
summary: Bookmark Highlights
|
|
||||||
description: |
|
|
||||||
This route returns a given bookmark's highlights.
|
|
||||||
|
|
||||||
responses:
|
|
||||||
"200":
|
|
||||||
description: Highlight list
|
|
||||||
content:
|
|
||||||
application/json:
|
|
||||||
schema:
|
|
||||||
type: array
|
|
||||||
items:
|
|
||||||
$ref: "#/components/schemas/annotationInfo"
|
|
||||||
|
|
||||||
# POST /bookmarks/{id}annotations
|
|
||||||
bookmarkAnnotationCreate:
|
|
||||||
summary: Highlight Create
|
|
||||||
description: |
|
|
||||||
This route creates a new highlight on a given bookmarks.
|
|
||||||
|
|
||||||
The highlight format is similar to the [Range API](https://developer.mozilla.org/en-US/docs/Web/API/Range)
|
|
||||||
with some differences:
|
|
||||||
|
|
||||||
- A range's start and end selectors are XPath selectors and must target an element.
|
|
||||||
- The offset is the text length from the begining of the selector, regardless of the traversed
|
|
||||||
potential children.
|
|
||||||
|
|
||||||
requestBody:
|
|
||||||
content:
|
|
||||||
application/json:
|
|
||||||
schema:
|
|
||||||
$ref: "#/components/schemas/annotationCreate"
|
|
||||||
|
|
||||||
responses:
|
|
||||||
"201":
|
|
||||||
description: Highlight created
|
|
||||||
content:
|
|
||||||
application/json:
|
|
||||||
schema:
|
|
||||||
$ref: "#/components/schemas/annotationInfo"
|
|
||||||
|
|
||||||
# PATCH /bookmarks/{id}annotations/{annotation_id}
|
|
||||||
bookmarkAnnotationUpdate:
|
|
||||||
summary: Highlight Update
|
|
||||||
description: |
|
|
||||||
This route updates then given highlight in the given bookmark.
|
|
||||||
|
|
||||||
requestBody:
|
|
||||||
content:
|
|
||||||
application/json:
|
|
||||||
schema:
|
|
||||||
$ref: "#/components/schemas/annotationUpdate"
|
|
||||||
|
|
||||||
responses:
|
|
||||||
"200":
|
|
||||||
description: Update result
|
|
||||||
content:
|
|
||||||
application/json:
|
|
||||||
schema:
|
|
||||||
properties:
|
|
||||||
updated:
|
|
||||||
type: string
|
|
||||||
format: date-time
|
|
||||||
annotations:
|
|
||||||
type: array
|
|
||||||
items:
|
|
||||||
$ref: "#/components/schemas/annotationInfo"
|
|
||||||
|
|
||||||
|
|
||||||
# DELETE /bookmarks/{id}annotations/{annotation_id}
|
|
||||||
bookmarkAnnotationDelete:
|
|
||||||
summary: Highlight Delete
|
|
||||||
description: |
|
|
||||||
This route removes the given highlight in the given bookmark.
|
|
||||||
|
|
||||||
responses:
|
|
||||||
"204":
|
|
||||||
description: Highlight removed
|
|
||||||
|
|
||||||
# GET /bookmarks/collections
|
|
||||||
collectionList:
|
|
||||||
summary: Collection List
|
|
||||||
description: |
|
|
||||||
This route returns all the current user's collections.
|
|
||||||
|
|
||||||
responses:
|
|
||||||
"200":
|
|
||||||
description: Collection list
|
|
||||||
content:
|
|
||||||
application/json:
|
|
||||||
schema:
|
|
||||||
type: array
|
|
||||||
items:
|
|
||||||
$ref: "#/components/schemas/collectionInfo"
|
|
||||||
|
|
||||||
# POST /bookmarks/collections
|
|
||||||
collectionCreate:
|
|
||||||
summary: Collection Create
|
|
||||||
description: |
|
|
||||||
This route creates a new collection.
|
|
||||||
|
|
||||||
requestBody:
|
|
||||||
content:
|
|
||||||
application/json:
|
|
||||||
schema:
|
|
||||||
$ref: "#/components/schemas/collectionCreate"
|
|
||||||
|
|
||||||
# GET /bookmarks/collections/{id}
|
|
||||||
collectionInfo:
|
|
||||||
summary: Collection Details
|
|
||||||
description: |
|
|
||||||
This route returns a given collection information.
|
|
||||||
|
|
||||||
responses:
|
|
||||||
"200":
|
|
||||||
description: Collection information
|
|
||||||
content:
|
|
||||||
application/json:
|
|
||||||
schema:
|
|
||||||
$ref: "#/components/schemas/collectionInfo"
|
|
||||||
|
|
||||||
# PATH /bookmarks/collections/{id}
|
|
||||||
collectionUpdate:
|
|
||||||
summary: Collection Update
|
|
||||||
description: |
|
|
||||||
This route updates a given collection. It returns a mapping of updated fields.
|
|
||||||
|
|
||||||
requestBody:
|
|
||||||
content:
|
|
||||||
application/json:
|
|
||||||
schema:
|
|
||||||
$ref: "#/components/schemas/collectionUpdate"
|
|
||||||
|
|
||||||
responses:
|
|
||||||
"200":
|
|
||||||
description: Updated fields
|
|
||||||
content:
|
|
||||||
application/json:
|
|
||||||
schema:
|
|
||||||
$ref: "#/components/schemas/collectionSummary"
|
|
||||||
|
|
||||||
# DELETE /bookmarks/collections/{id}
|
|
||||||
collectionDelete:
|
|
||||||
summary: Collection Delete
|
|
||||||
description: |
|
|
||||||
This route deletes a given collection.
|
|
||||||
|
|
||||||
responses:
|
|
||||||
"204":
|
|
||||||
description: Collection deleted
|
|
||||||
|
|
||||||
# POST /bookmarks/import/text
|
|
||||||
importMultipartGeneric:
|
|
||||||
requestBody:
|
|
||||||
content:
|
|
||||||
text/plain:
|
|
||||||
schema:
|
|
||||||
type: string
|
|
||||||
description: File content
|
|
||||||
multipart/form-data:
|
|
||||||
schema:
|
|
||||||
properties:
|
|
||||||
data:
|
|
||||||
type: string
|
|
||||||
format: binary
|
|
||||||
|
|
||||||
importTextFile:
|
|
||||||
summary: Import a Text File
|
|
||||||
description: |
|
|
||||||
This route creates bookmarks from a text file that contains one URL
|
|
||||||
per line.
|
|
||||||
|
|
||||||
importBrowserBookmarks:
|
|
||||||
summary: Import Browser Bookmarks
|
|
||||||
description: |
|
|
||||||
This route creates bookmarks from an HTML file generated by an export of a browser's
|
|
||||||
bookmarks.
|
|
||||||
|
|
||||||
importPocket:
|
|
||||||
summary: Import Pocket Saves
|
|
||||||
description: |
|
|
||||||
This route creates bookmarks from an HTML file generated by Pocket export tool.
|
|
||||||
Go to [https://getpocket.com/export](https://getpocket.com/export) to generate
|
|
||||||
such a file.
|
|
||||||
|
|
||||||
importWallabag:
|
|
||||||
summary: Import Wallabag Articles
|
|
||||||
description: |
|
|
||||||
This route imports articles from Wallabag using its API.
|
|
||||||
|
|
||||||
You must create an API client in Wallabag and use its "Client ID" and "Client Secret"
|
|
||||||
in this route's payload.
|
|
||||||
|
|
||||||
requestBody:
|
|
||||||
content:
|
|
||||||
application/json:
|
|
||||||
schema:
|
|
||||||
$ref: "#/components/schemas/wallabagImport"
|
|
||||||
@ -1,27 +0,0 @@
|
|||||||
---
|
|
||||||
# SPDX-FileCopyrightText: © 2024 Olivier Meunier <olivier@neokraft.net>
|
|
||||||
#
|
|
||||||
# SPDX-License-Identifier: AGPL-3.0-only
|
|
||||||
|
|
||||||
sortable:
|
|
||||||
parameters:
|
|
||||||
- name: sort
|
|
||||||
in: query
|
|
||||||
description: Sorting parameters
|
|
||||||
schema:
|
|
||||||
type: array
|
|
||||||
items:
|
|
||||||
type: string
|
|
||||||
enum:
|
|
||||||
- created
|
|
||||||
- -created
|
|
||||||
- domain
|
|
||||||
- -domain
|
|
||||||
- duration
|
|
||||||
- -duration
|
|
||||||
- published
|
|
||||||
- -published
|
|
||||||
- site
|
|
||||||
- -site
|
|
||||||
- title
|
|
||||||
- -title
|
|
||||||
@ -1,580 +0,0 @@
|
|||||||
---
|
|
||||||
# SPDX-FileCopyrightText: © 2023 Olivier Meunier <olivier@neokraft.net>
|
|
||||||
#
|
|
||||||
# SPDX-License-Identifier: AGPL-3.0-only
|
|
||||||
|
|
||||||
schemas:
|
|
||||||
bookmarkSummary:
|
|
||||||
type: object
|
|
||||||
properties:
|
|
||||||
id:
|
|
||||||
type: string
|
|
||||||
format: short-uid
|
|
||||||
description: Bookmark's ID
|
|
||||||
href:
|
|
||||||
type: string
|
|
||||||
format: uri
|
|
||||||
description: Link to the bookmark info
|
|
||||||
created:
|
|
||||||
type: string
|
|
||||||
format: date-time
|
|
||||||
description: Creation date
|
|
||||||
updated:
|
|
||||||
type: string
|
|
||||||
format: date-time
|
|
||||||
description: Last update
|
|
||||||
state:
|
|
||||||
type: integer
|
|
||||||
enum: [0, 1, 2]
|
|
||||||
description: |
|
|
||||||
Indicates the state of the bookmark.
|
|
||||||
- `0`: loaded
|
|
||||||
- `1`: error
|
|
||||||
- `2`: loading
|
|
||||||
loaded:
|
|
||||||
type: boolean
|
|
||||||
description: Becomes true when the bookmark is ready (regardless of its error state)
|
|
||||||
url:
|
|
||||||
type: string
|
|
||||||
format: uri
|
|
||||||
description: Bookmark's original URL
|
|
||||||
title:
|
|
||||||
type: string
|
|
||||||
description: Bookmark's title
|
|
||||||
site_name:
|
|
||||||
type: string
|
|
||||||
description: Bookmark's site name
|
|
||||||
site:
|
|
||||||
type: string
|
|
||||||
format: hostname
|
|
||||||
description: Bookmark's site host name
|
|
||||||
published:
|
|
||||||
type: [string]
|
|
||||||
format: date-time
|
|
||||||
nullable: true
|
|
||||||
description: Publication date. Can be `null` when unknown.
|
|
||||||
authors:
|
|
||||||
type: array
|
|
||||||
items:
|
|
||||||
type: string
|
|
||||||
description: Author list
|
|
||||||
lang:
|
|
||||||
type: string
|
|
||||||
description: Language Code
|
|
||||||
text_direction:
|
|
||||||
type: string
|
|
||||||
enum: [rtl, ltr]
|
|
||||||
description: |
|
|
||||||
Direction of the article's text. It can be empty when it's unknown.
|
|
||||||
document_type:
|
|
||||||
type: string
|
|
||||||
description: |
|
|
||||||
The bookmark document type. This is usualy the same value as `type` but it can differ
|
|
||||||
depending on the extraction process.
|
|
||||||
type:
|
|
||||||
type: string
|
|
||||||
enum: [article, photo, video]
|
|
||||||
description: |
|
|
||||||
The bookmark type. Unlike `document_type`, this can only be one of the 3 values.
|
|
||||||
has_article:
|
|
||||||
type: boolean
|
|
||||||
description: |
|
|
||||||
Indicates whether the bookmarks contains an article. Please not that
|
|
||||||
there can be an article on any type.
|
|
||||||
description:
|
|
||||||
type: string
|
|
||||||
description: |
|
|
||||||
Bookmark's short description, when it exists. It's always an unformatted text.
|
|
||||||
is_deleted:
|
|
||||||
type: boolean
|
|
||||||
description: |
|
|
||||||
`true` when the bookmark is scheduled for deletion.
|
|
||||||
is_marked:
|
|
||||||
type: boolean
|
|
||||||
description: |
|
|
||||||
`true` when the bookmark is in the favorites.
|
|
||||||
is_archived:
|
|
||||||
type: boolean
|
|
||||||
description: |
|
|
||||||
`true` when the bookmark is in the archives.
|
|
||||||
read_progress:
|
|
||||||
type: integer
|
|
||||||
minimum: 0
|
|
||||||
maximum: 100
|
|
||||||
description: Reading progress percentage.
|
|
||||||
labels:
|
|
||||||
type: array
|
|
||||||
items:
|
|
||||||
type: string
|
|
||||||
description: Bookmark's labels
|
|
||||||
word_count:
|
|
||||||
type: integer
|
|
||||||
minimum: 0
|
|
||||||
description: Number of words in the article, used to compute the reading time.
|
|
||||||
reading_time:
|
|
||||||
type: integer
|
|
||||||
minimum: 0
|
|
||||||
description: |
|
|
||||||
Duration of the article, in minutes. Either the actual duration for a
|
|
||||||
video or a reading time based on the word count.
|
|
||||||
resources:
|
|
||||||
type: object
|
|
||||||
description: |
|
|
||||||
This contains a list of resources associated with the bookmark.
|
|
||||||
The only fields that are always present are `log` and `props`.
|
|
||||||
The `article` field is only present when a bookmark provides a
|
|
||||||
text content. Other image fields depend on what was found during
|
|
||||||
extraction.
|
|
||||||
properties:
|
|
||||||
article:
|
|
||||||
$ref: "#/components/schemas/bookmarkResource"
|
|
||||||
description: Link to the article, when there is one.
|
|
||||||
icon:
|
|
||||||
$ref: "#/components/schemas/bookmarkResourceImage"
|
|
||||||
description: Link and information for the site icon.
|
|
||||||
image:
|
|
||||||
$ref: "#/components/schemas/bookmarkResourceImage"
|
|
||||||
description: Link and information for the article image.
|
|
||||||
thumbnail:
|
|
||||||
$ref: "#/components/schemas/bookmarkResourceImage"
|
|
||||||
description: Link and information for the article thumbnail.
|
|
||||||
log:
|
|
||||||
$ref: "#/components/schemas/bookmarkResource"
|
|
||||||
description: Link to the extraction log.
|
|
||||||
props:
|
|
||||||
$ref: "#/components/schemas/bookmarkResource"
|
|
||||||
description: Link to the bookmark's extra properties.
|
|
||||||
|
|
||||||
bookmarkResource:
|
|
||||||
type: object
|
|
||||||
properties:
|
|
||||||
src:
|
|
||||||
type: string
|
|
||||||
format: uri
|
|
||||||
description: URL of the resource
|
|
||||||
|
|
||||||
bookmarkResourceImage:
|
|
||||||
allOf:
|
|
||||||
- $ref: "#/components/schemas/bookmarkResource"
|
|
||||||
- type: object
|
|
||||||
properties:
|
|
||||||
height:
|
|
||||||
type: integer
|
|
||||||
description: Image height
|
|
||||||
width:
|
|
||||||
type: integer
|
|
||||||
description: Image width
|
|
||||||
|
|
||||||
bookmarkInfo:
|
|
||||||
allOf:
|
|
||||||
- $ref: "#/components/schemas/bookmarkSummary"
|
|
||||||
- type: object
|
|
||||||
properties:
|
|
||||||
read_anchor:
|
|
||||||
type: string
|
|
||||||
description: CSS selector of the last seen element.
|
|
||||||
links:
|
|
||||||
description: |
|
|
||||||
This contains the list of all the links collected in the
|
|
||||||
retrieved article.
|
|
||||||
type: array
|
|
||||||
items:
|
|
||||||
properties:
|
|
||||||
url:
|
|
||||||
type: string
|
|
||||||
format: uri
|
|
||||||
description: Link URI
|
|
||||||
domain:
|
|
||||||
type: string
|
|
||||||
format: hostname
|
|
||||||
description: Link's domain
|
|
||||||
title:
|
|
||||||
type: string
|
|
||||||
description: Link's title
|
|
||||||
is_page:
|
|
||||||
type: boolean
|
|
||||||
description: |
|
|
||||||
`true` when the destination is a web page
|
|
||||||
content_type:
|
|
||||||
type: string
|
|
||||||
description: MIME type of the destination
|
|
||||||
|
|
||||||
bookmarkCreate:
|
|
||||||
required: [url]
|
|
||||||
properties:
|
|
||||||
url:
|
|
||||||
type: string
|
|
||||||
description: URL to fetch
|
|
||||||
title:
|
|
||||||
type: string
|
|
||||||
description: Title of the bookmark
|
|
||||||
labels:
|
|
||||||
type: array
|
|
||||||
items:
|
|
||||||
type: string
|
|
||||||
description: List of labels to set to the bookmark
|
|
||||||
|
|
||||||
bookmarkUpdate:
|
|
||||||
properties:
|
|
||||||
title:
|
|
||||||
type: string
|
|
||||||
description: New bookmark's title
|
|
||||||
is_marked:
|
|
||||||
type: boolean
|
|
||||||
description: Favortie state
|
|
||||||
is_archived:
|
|
||||||
type: boolean
|
|
||||||
description: Archive state
|
|
||||||
is_deleted:
|
|
||||||
type: boolean
|
|
||||||
description: |
|
|
||||||
If `true`, schedules the bookmark for deletion, otherwise, cancels any scheduled deletion
|
|
||||||
read_progress:
|
|
||||||
type: integer
|
|
||||||
minimum: 0
|
|
||||||
maximum: 100
|
|
||||||
description: Reading progress percentage
|
|
||||||
read_anchor:
|
|
||||||
type: string
|
|
||||||
description: CSS selector of the last seen element
|
|
||||||
labels:
|
|
||||||
type: array
|
|
||||||
items:
|
|
||||||
type: string
|
|
||||||
description: Replaces the bookmark's labels
|
|
||||||
add_labels:
|
|
||||||
items:
|
|
||||||
type: string
|
|
||||||
description: Add the given labels to the bookmark
|
|
||||||
remove_labels:
|
|
||||||
items:
|
|
||||||
type: string
|
|
||||||
description: Remove the given labels from the bookmark
|
|
||||||
|
|
||||||
bookmarkUpdated:
|
|
||||||
required: [href, id, updated]
|
|
||||||
properties:
|
|
||||||
href:
|
|
||||||
type: string
|
|
||||||
format: uri
|
|
||||||
description: Bookmark URI
|
|
||||||
id:
|
|
||||||
type: string
|
|
||||||
format: short-uid
|
|
||||||
description: Bookmark's ID
|
|
||||||
updated:
|
|
||||||
type: string
|
|
||||||
format: date-time
|
|
||||||
description: Last update
|
|
||||||
title:
|
|
||||||
type: string
|
|
||||||
description: Bookmark Title
|
|
||||||
is_marked:
|
|
||||||
type: string
|
|
||||||
description: Favorite status
|
|
||||||
is_archived:
|
|
||||||
type: string
|
|
||||||
description: Archive status
|
|
||||||
is_deleted:
|
|
||||||
type: string
|
|
||||||
description: Scheduled deletion status
|
|
||||||
read_progress:
|
|
||||||
type: integer
|
|
||||||
minimum: 0
|
|
||||||
maximum: 100
|
|
||||||
description: Reading progress percentage
|
|
||||||
read_anchor:
|
|
||||||
type: string
|
|
||||||
description: CSS selector of the last seen element
|
|
||||||
labels:
|
|
||||||
type: string
|
|
||||||
description: New label list
|
|
||||||
|
|
||||||
bookmarkShareLink:
|
|
||||||
properties:
|
|
||||||
url:
|
|
||||||
type: string
|
|
||||||
description: Public URL
|
|
||||||
expires:
|
|
||||||
type: string
|
|
||||||
format: date-time
|
|
||||||
description: Expiration date
|
|
||||||
title:
|
|
||||||
type: string
|
|
||||||
description: Bookmark title
|
|
||||||
id:
|
|
||||||
type: string
|
|
||||||
description: Bookmark ID
|
|
||||||
|
|
||||||
bookmarkShareEmail:
|
|
||||||
properties:
|
|
||||||
email:
|
|
||||||
type: string
|
|
||||||
format: email
|
|
||||||
format:
|
|
||||||
type: string
|
|
||||||
enum: ["html", "epub"]
|
|
||||||
example:
|
|
||||||
email: alice@localhost
|
|
||||||
format: html
|
|
||||||
|
|
||||||
labelInfo:
|
|
||||||
properties:
|
|
||||||
name:
|
|
||||||
type: string
|
|
||||||
description: Label's name
|
|
||||||
count:
|
|
||||||
type: integer
|
|
||||||
description: Number of bookmarks with this label
|
|
||||||
href:
|
|
||||||
type: string
|
|
||||||
format: uri
|
|
||||||
description: Link to the label info
|
|
||||||
href_bookmarks:
|
|
||||||
type: string
|
|
||||||
format: uri
|
|
||||||
description: Link to the bookmarks with this label
|
|
||||||
|
|
||||||
labelUpdate:
|
|
||||||
properties:
|
|
||||||
name:
|
|
||||||
type: string
|
|
||||||
description: New label
|
|
||||||
|
|
||||||
annotationSummary:
|
|
||||||
properties:
|
|
||||||
id:
|
|
||||||
type: string
|
|
||||||
format: short-uid
|
|
||||||
description: Highlight ID
|
|
||||||
href:
|
|
||||||
type: string
|
|
||||||
format: uri
|
|
||||||
description: Link to the highlight
|
|
||||||
text:
|
|
||||||
type: string
|
|
||||||
description: Highlighted text
|
|
||||||
created:
|
|
||||||
type: string
|
|
||||||
format: date-time
|
|
||||||
description: Highlight creation date
|
|
||||||
bookmark_id:
|
|
||||||
type: string
|
|
||||||
format: short-uid
|
|
||||||
description: Bookmark ID
|
|
||||||
bookmark_href:
|
|
||||||
type: string
|
|
||||||
format: uri
|
|
||||||
description: Link to the bookmark information
|
|
||||||
bookmark_url:
|
|
||||||
type: string
|
|
||||||
format: uri
|
|
||||||
description: Original bookmark's URL
|
|
||||||
bookmark_title:
|
|
||||||
type: string
|
|
||||||
description: Title of the bookmark
|
|
||||||
bookmark_site_name:
|
|
||||||
type: string
|
|
||||||
description: Bookmark's site name
|
|
||||||
|
|
||||||
annotationInfo:
|
|
||||||
properties:
|
|
||||||
id:
|
|
||||||
type: string
|
|
||||||
format: short-uid
|
|
||||||
description: Highlight ID
|
|
||||||
start_selector:
|
|
||||||
type: string
|
|
||||||
description: Start element's XPath selector
|
|
||||||
start_offset:
|
|
||||||
type: integer
|
|
||||||
description: Start element's text offset
|
|
||||||
end_selector:
|
|
||||||
type: string
|
|
||||||
description: End element's XPath selector
|
|
||||||
end_offset:
|
|
||||||
type: integer
|
|
||||||
description: End element's text offset
|
|
||||||
created:
|
|
||||||
type: string
|
|
||||||
format: date-time
|
|
||||||
description: Highlight creation date
|
|
||||||
text:
|
|
||||||
type: string
|
|
||||||
description: Highlighted text
|
|
||||||
|
|
||||||
annotationCreate:
|
|
||||||
required: [start_selector, start_offset, end_selector, end_offset, color]
|
|
||||||
properties:
|
|
||||||
start_selector:
|
|
||||||
type: string
|
|
||||||
description: Start element's XPath selector
|
|
||||||
start_offset:
|
|
||||||
type: integer
|
|
||||||
description: Start element's text offset
|
|
||||||
end_selector:
|
|
||||||
type: string
|
|
||||||
description: End element's XPath selector
|
|
||||||
end_offset:
|
|
||||||
type: integer
|
|
||||||
description: End element's text offset
|
|
||||||
color:
|
|
||||||
type: color
|
|
||||||
description: Annotation color
|
|
||||||
|
|
||||||
annotationUpdate:
|
|
||||||
required: [color]
|
|
||||||
properties:
|
|
||||||
color:
|
|
||||||
type: color
|
|
||||||
description: Annotation color
|
|
||||||
|
|
||||||
collectionSummary:
|
|
||||||
properties:
|
|
||||||
updated:
|
|
||||||
type: string
|
|
||||||
format: date-time
|
|
||||||
description: Last update date
|
|
||||||
name:
|
|
||||||
type: string
|
|
||||||
description: Collection's name
|
|
||||||
is_pinned:
|
|
||||||
type: boolean
|
|
||||||
description: |
|
|
||||||
`true` when the collection is pinned
|
|
||||||
is_deleted:
|
|
||||||
type: boolean
|
|
||||||
description: Collection is scheduled for deletion
|
|
||||||
search:
|
|
||||||
type: string
|
|
||||||
description: Search string
|
|
||||||
title:
|
|
||||||
type: string
|
|
||||||
description: Title filter
|
|
||||||
author:
|
|
||||||
type: string
|
|
||||||
description: Author filter
|
|
||||||
site:
|
|
||||||
type: string
|
|
||||||
description: Site (name, host or domain) filter
|
|
||||||
type:
|
|
||||||
type: array
|
|
||||||
items:
|
|
||||||
type: string
|
|
||||||
enum: [article, photo, video]
|
|
||||||
description: Type filter
|
|
||||||
labels:
|
|
||||||
type: string
|
|
||||||
description: Label filter
|
|
||||||
read_status:
|
|
||||||
type: array
|
|
||||||
items:
|
|
||||||
type: string
|
|
||||||
enum: [unread, reading, read]
|
|
||||||
description: Read progress status
|
|
||||||
is_marked:
|
|
||||||
type: boolean
|
|
||||||
description: Favorite filter
|
|
||||||
is_archived:
|
|
||||||
type: boolean
|
|
||||||
description: Archive filter
|
|
||||||
range_start:
|
|
||||||
type: string
|
|
||||||
description: From date filter
|
|
||||||
range_end:
|
|
||||||
type: string
|
|
||||||
description: To date filter
|
|
||||||
|
|
||||||
collectionInfo:
|
|
||||||
allOf:
|
|
||||||
- type: object
|
|
||||||
properties:
|
|
||||||
id:
|
|
||||||
type: string
|
|
||||||
format: short-uid
|
|
||||||
description: Collection ID
|
|
||||||
href:
|
|
||||||
type: string
|
|
||||||
format: uri
|
|
||||||
description: Collection URL
|
|
||||||
created:
|
|
||||||
type: string
|
|
||||||
format: date-time
|
|
||||||
description: Creation date
|
|
||||||
- $ref: "#/components/schemas/collectionSummary"
|
|
||||||
|
|
||||||
|
|
||||||
collectionCreate:
|
|
||||||
properties:
|
|
||||||
name:
|
|
||||||
type: string
|
|
||||||
description: Collection's name
|
|
||||||
is_pinned:
|
|
||||||
type: boolean
|
|
||||||
description: |
|
|
||||||
`true` when the collection is pinned
|
|
||||||
is_deleted:
|
|
||||||
type: boolean
|
|
||||||
description: Collection is scheduled for deletion
|
|
||||||
search:
|
|
||||||
type: string
|
|
||||||
description: Search string
|
|
||||||
title:
|
|
||||||
type: string
|
|
||||||
description: Title filter
|
|
||||||
author:
|
|
||||||
type: string
|
|
||||||
description: Author filter
|
|
||||||
site:
|
|
||||||
type: string
|
|
||||||
description: Site (name, host or domain) filter
|
|
||||||
type:
|
|
||||||
type: array
|
|
||||||
items:
|
|
||||||
type: string
|
|
||||||
enum: [article, photo, video]
|
|
||||||
description: Type filter
|
|
||||||
labels:
|
|
||||||
type: string
|
|
||||||
description: Label filter
|
|
||||||
read_status:
|
|
||||||
type: array
|
|
||||||
items:
|
|
||||||
type: string
|
|
||||||
enum: [unread, reading, read]
|
|
||||||
description: Read progress status
|
|
||||||
is_marked:
|
|
||||||
type: boolean
|
|
||||||
description: Favorite filter
|
|
||||||
is_archived:
|
|
||||||
type: boolean
|
|
||||||
description: Archive filter
|
|
||||||
range_start:
|
|
||||||
type: string
|
|
||||||
description: From date filter
|
|
||||||
range_end:
|
|
||||||
type: string
|
|
||||||
description: To date filter
|
|
||||||
|
|
||||||
collectionUpdate:
|
|
||||||
allOf:
|
|
||||||
- $ref: "#/components/schemas/collectionCreate"
|
|
||||||
|
|
||||||
wallabagImport:
|
|
||||||
properties:
|
|
||||||
url:
|
|
||||||
type: string
|
|
||||||
format: uri
|
|
||||||
description: Your Wallabag instance's URL
|
|
||||||
username:
|
|
||||||
type: string
|
|
||||||
description: Your Wallabag username
|
|
||||||
password:
|
|
||||||
type: string
|
|
||||||
description: Your Wallabag password
|
|
||||||
client_id:
|
|
||||||
type: string
|
|
||||||
description: API Client ID
|
|
||||||
client_secret:
|
|
||||||
type: string
|
|
||||||
description: API Client Secret
|
|
||||||
@ -1,145 +0,0 @@
|
|||||||
---
|
|
||||||
# SPDX-FileCopyrightText: © 2023 Olivier Meunier <olivier@neokraft.net>
|
|
||||||
#
|
|
||||||
# SPDX-License-Identifier: AGPL-3.0-only
|
|
||||||
|
|
||||||
# GET /cookbook/extrack
|
|
||||||
extract:
|
|
||||||
summary: Extract Link
|
|
||||||
description: |
|
|
||||||
**NOTE: Only available for user in the admin group.**
|
|
||||||
|
|
||||||
This route extracts a link and returns the extraction result.
|
|
||||||
|
|
||||||
You can pass an `Accept` header to the request, with one of the following values:
|
|
||||||
|
|
||||||
- `application/json` (default) returns a JSON response
|
|
||||||
- `text/html` returns an HTML response with all the media included as base64 encoded
|
|
||||||
URLs.
|
|
||||||
|
|
||||||
parameters:
|
|
||||||
- name: url
|
|
||||||
in: query
|
|
||||||
required: true
|
|
||||||
schema:
|
|
||||||
type: string
|
|
||||||
format: uri
|
|
||||||
description: URL to extract
|
|
||||||
|
|
||||||
responses:
|
|
||||||
"200":
|
|
||||||
description: |
|
|
||||||
Extraction result.
|
|
||||||
content:
|
|
||||||
application/json:
|
|
||||||
schema:
|
|
||||||
properties:
|
|
||||||
url:
|
|
||||||
type: string
|
|
||||||
format: uri
|
|
||||||
description: The extracted URL
|
|
||||||
logs:
|
|
||||||
type: array
|
|
||||||
items:
|
|
||||||
type: string
|
|
||||||
description: Extraction log
|
|
||||||
errors:
|
|
||||||
type: array
|
|
||||||
items:
|
|
||||||
type: string
|
|
||||||
description: Extraction errors, if any
|
|
||||||
meta:
|
|
||||||
type: object
|
|
||||||
additionalProperties:
|
|
||||||
type: array
|
|
||||||
items:
|
|
||||||
type: string
|
|
||||||
description: |
|
|
||||||
Contains the meta tags extracted from the page.
|
|
||||||
properties:
|
|
||||||
properties:
|
|
||||||
json-ld:
|
|
||||||
type: array
|
|
||||||
items:
|
|
||||||
type: object
|
|
||||||
description: A list of JSON-LD documents retrieved during the extraction
|
|
||||||
link:
|
|
||||||
type: array
|
|
||||||
items:
|
|
||||||
type: object
|
|
||||||
patternProperties:
|
|
||||||
"^@.+":
|
|
||||||
type: string
|
|
||||||
description: Link attribute, always starting with `@`
|
|
||||||
description: A list of all `link` tags retrieved during the extraction
|
|
||||||
meta:
|
|
||||||
type: array
|
|
||||||
items:
|
|
||||||
type: object
|
|
||||||
patternProperties:
|
|
||||||
"^@.+":
|
|
||||||
type: string
|
|
||||||
description: Meta attribute, always starting with `@`
|
|
||||||
description: A list of all `meta` tags retrieved during the extraction
|
|
||||||
domain:
|
|
||||||
type: string
|
|
||||||
format: hostname
|
|
||||||
description: Page's domain name
|
|
||||||
title:
|
|
||||||
type: string
|
|
||||||
description: Page's title
|
|
||||||
authors:
|
|
||||||
type: "[string]"
|
|
||||||
description: Page's author list
|
|
||||||
site:
|
|
||||||
type: string
|
|
||||||
format: hostname
|
|
||||||
description: Page's site
|
|
||||||
site_name:
|
|
||||||
type: string
|
|
||||||
description: Page's site name
|
|
||||||
lang:
|
|
||||||
type: string
|
|
||||||
description: Language Code
|
|
||||||
text_direction:
|
|
||||||
type: string
|
|
||||||
enum: [rtl, ltr]
|
|
||||||
description: |
|
|
||||||
Direction of the article's text. It can be empty when it's unknown.
|
|
||||||
date:
|
|
||||||
type: [string]
|
|
||||||
format: date-time
|
|
||||||
nullable: true
|
|
||||||
description: Publication date. Can be `null` when unknown.
|
|
||||||
document_type:
|
|
||||||
type: string
|
|
||||||
description: |
|
|
||||||
The detected document type. The value is usualy `article`, `photo` or `video`
|
|
||||||
but can vary, based on the extraction process.
|
|
||||||
description:
|
|
||||||
type: string
|
|
||||||
description: |
|
|
||||||
Page's short description, when it exists. It's always an unformatted text.
|
|
||||||
html:
|
|
||||||
type: string
|
|
||||||
description: |
|
|
||||||
The HTML content after processing.
|
|
||||||
embed:
|
|
||||||
type: string
|
|
||||||
description: |
|
|
||||||
The oembed HTML fragment, when it exists. It usualy contains an iframe when
|
|
||||||
extracting videos.
|
|
||||||
images:
|
|
||||||
properties:
|
|
||||||
additionalProperties:
|
|
||||||
properties:
|
|
||||||
size:
|
|
||||||
type: "[integer]"
|
|
||||||
description: The image size in pixels
|
|
||||||
encoded:
|
|
||||||
type: string
|
|
||||||
description: The base64 URI encoded image
|
|
||||||
|
|
||||||
text/html:
|
|
||||||
schema:
|
|
||||||
type: string
|
|
||||||
@ -1,55 +0,0 @@
|
|||||||
---
|
|
||||||
# SPDX-FileCopyrightText: © 2023 Olivier Meunier <olivier@neokraft.net>
|
|
||||||
#
|
|
||||||
# SPDX-License-Identifier: AGPL-3.0-only
|
|
||||||
|
|
||||||
auth:
|
|
||||||
summary: Authenticate
|
|
||||||
description: |
|
|
||||||
This route performs the authentication with a username and a password and returns a token
|
|
||||||
that you can use for all API requests.
|
|
||||||
|
|
||||||
You don't need to perform a request to this route each time you're using the API, only do it
|
|
||||||
once and keep the token somehow. You can use this route to provide a first time authentication
|
|
||||||
in a mobile application or any API client you may build and only store the resulting token.
|
|
||||||
|
|
||||||
You MUST provide an application name.
|
|
||||||
|
|
||||||
Alternatively, you can [create an authentication token](../profile/tokens) directly from
|
|
||||||
Readeck.
|
|
||||||
|
|
||||||
requestBody:
|
|
||||||
content:
|
|
||||||
application/json:
|
|
||||||
schema:
|
|
||||||
$ref: "#/components/schemas/authenticationForm"
|
|
||||||
|
|
||||||
responses:
|
|
||||||
"201":
|
|
||||||
description: Authentication success
|
|
||||||
content:
|
|
||||||
application/json:
|
|
||||||
schema:
|
|
||||||
$ref: "#/components/schemas/authenticationResult"
|
|
||||||
|
|
||||||
"403":
|
|
||||||
description: Authentication failed
|
|
||||||
content:
|
|
||||||
application/json:
|
|
||||||
schema:
|
|
||||||
$ref: "#/components/schemas/message"
|
|
||||||
|
|
||||||
# GET /profile
|
|
||||||
profile:
|
|
||||||
summary: User Profile
|
|
||||||
description: |
|
|
||||||
This route returns the current user's profile information. This includes the user information
|
|
||||||
and preferences, and the authentication provider with its permissions.
|
|
||||||
|
|
||||||
responses:
|
|
||||||
"200":
|
|
||||||
description: Profile information
|
|
||||||
content:
|
|
||||||
application/json:
|
|
||||||
schema:
|
|
||||||
$ref: "#/components/schemas/userProfile"
|
|
||||||
@ -1,143 +0,0 @@
|
|||||||
---
|
|
||||||
# SPDX-FileCopyrightText: © 2023 Olivier Meunier <olivier@neokraft.net>
|
|
||||||
#
|
|
||||||
# SPDX-License-Identifier: AGPL-3.0-only
|
|
||||||
|
|
||||||
schemas:
|
|
||||||
authenticationForm:
|
|
||||||
type: object
|
|
||||||
required: [username, password, application]
|
|
||||||
properties:
|
|
||||||
username:
|
|
||||||
type: string
|
|
||||||
description: Username
|
|
||||||
password:
|
|
||||||
type: string
|
|
||||||
description: Password
|
|
||||||
application:
|
|
||||||
type: string
|
|
||||||
description: Application name. This can be anything.
|
|
||||||
roles:
|
|
||||||
type: array
|
|
||||||
items:
|
|
||||||
type: string
|
|
||||||
description: A list of roles to restrict the new token access.
|
|
||||||
example:
|
|
||||||
username: alice
|
|
||||||
password: "1234"
|
|
||||||
application: api doc
|
|
||||||
|
|
||||||
authenticationResult:
|
|
||||||
type: object
|
|
||||||
properties:
|
|
||||||
id:
|
|
||||||
type: string
|
|
||||||
description: Token ID
|
|
||||||
token:
|
|
||||||
type: string
|
|
||||||
description: Authentication token. This is the value you must store in your application.
|
|
||||||
example:
|
|
||||||
{
|
|
||||||
"id": "RFutYEAVM95DUDLUDnhbQm",
|
|
||||||
"token": "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9.eyJqdxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
|
|
||||||
}
|
|
||||||
|
|
||||||
userProfile:
|
|
||||||
type: object
|
|
||||||
properties:
|
|
||||||
provider:
|
|
||||||
description: Authentication provider information
|
|
||||||
type: object
|
|
||||||
properties:
|
|
||||||
id:
|
|
||||||
type: string
|
|
||||||
format: short-uid
|
|
||||||
description: Authentication provider ID (ie. the token ID)
|
|
||||||
name:
|
|
||||||
type: string
|
|
||||||
description: Provider name
|
|
||||||
application:
|
|
||||||
type: string
|
|
||||||
description: The registered application name
|
|
||||||
roles:
|
|
||||||
type: array
|
|
||||||
items:
|
|
||||||
type: string
|
|
||||||
description: Roles granted for this session
|
|
||||||
permissions:
|
|
||||||
type: array
|
|
||||||
items:
|
|
||||||
type: string
|
|
||||||
description: Permissions granted for this session
|
|
||||||
user:
|
|
||||||
description: User information
|
|
||||||
type: object
|
|
||||||
properties:
|
|
||||||
username:
|
|
||||||
type: string
|
|
||||||
description: Username
|
|
||||||
email:
|
|
||||||
type: string
|
|
||||||
format: email
|
|
||||||
description: User email
|
|
||||||
created:
|
|
||||||
type: string
|
|
||||||
format: date-time
|
|
||||||
description: Creation date
|
|
||||||
updated:
|
|
||||||
type: string
|
|
||||||
format: date-time
|
|
||||||
description: Last update date
|
|
||||||
settings:
|
|
||||||
description: User settings
|
|
||||||
type: object
|
|
||||||
properties:
|
|
||||||
debug_info:
|
|
||||||
type: boolean
|
|
||||||
description: Enable debug information
|
|
||||||
reader_settings:
|
|
||||||
description: Reader settings
|
|
||||||
type: object
|
|
||||||
properties:
|
|
||||||
font:
|
|
||||||
type: string
|
|
||||||
font_size:
|
|
||||||
type: integer
|
|
||||||
line_height:
|
|
||||||
type: integer
|
|
||||||
example:
|
|
||||||
{
|
|
||||||
"provider": {
|
|
||||||
"name": "bearer token",
|
|
||||||
"id": "X4bmnMRcnDhQtu5y33qzTp",
|
|
||||||
"application": "internal",
|
|
||||||
"roles": [
|
|
||||||
"scoped_bookmarks_r",
|
|
||||||
"scoped_bookmarks_w"
|
|
||||||
],
|
|
||||||
"permissions": [
|
|
||||||
"api:bookmarks:collections:read",
|
|
||||||
"api:bookmarks:collections:write",
|
|
||||||
"api:bookmarks:export",
|
|
||||||
"api:bookmarks:read",
|
|
||||||
"api:bookmarks:write",
|
|
||||||
"api:opds:read",
|
|
||||||
"api:profile:read",
|
|
||||||
"api:profile:tokens:delete"
|
|
||||||
]
|
|
||||||
},
|
|
||||||
"user": {
|
|
||||||
"username": "alice",
|
|
||||||
"email": "alice@localhost",
|
|
||||||
"created": "2023-08-27T13:32:11.704606963Z",
|
|
||||||
"updated": "2023-12-17T09:08:31.909723372Z",
|
|
||||||
"settings": {
|
|
||||||
"debug_info": false,
|
|
||||||
"reader_settings": {
|
|
||||||
"font": "serif",
|
|
||||||
"font_size": 3,
|
|
||||||
"line_height": 3
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
@ -1,125 +0,0 @@
|
|||||||
---
|
|
||||||
# SPDX-FileCopyrightText: © 2023 Olivier Meunier <olivier@neokraft.net>
|
|
||||||
#
|
|
||||||
# SPDX-License-Identifier: AGPL-3.0-only
|
|
||||||
|
|
||||||
authenticated:
|
|
||||||
responses:
|
|
||||||
"401":
|
|
||||||
description: |
|
|
||||||
Unauthorized. The request token found in the Authorization header is not valid.
|
|
||||||
content:
|
|
||||||
application/json:
|
|
||||||
schema:
|
|
||||||
$ref: "#/components/schemas/message"
|
|
||||||
"403":
|
|
||||||
description: |
|
|
||||||
Forbidden. The user doesn't have permission to fetch users for the specified,
|
|
||||||
but has other account permissions
|
|
||||||
content:
|
|
||||||
application/json:
|
|
||||||
schema:
|
|
||||||
$ref: "#/components/schemas/message"
|
|
||||||
|
|
||||||
paginated:
|
|
||||||
parameters:
|
|
||||||
- name: limit
|
|
||||||
in: query
|
|
||||||
description: Number of items per page
|
|
||||||
schema:
|
|
||||||
type: integer
|
|
||||||
- name: offset
|
|
||||||
in: query
|
|
||||||
description: Pagination offset
|
|
||||||
schema:
|
|
||||||
type: integer
|
|
||||||
|
|
||||||
responses:
|
|
||||||
'200':
|
|
||||||
headers:
|
|
||||||
Link:
|
|
||||||
description: Link to other pages in paginated results
|
|
||||||
schema:
|
|
||||||
type: array
|
|
||||||
items:
|
|
||||||
type: string
|
|
||||||
Current-Page:
|
|
||||||
description: Current page number
|
|
||||||
schema:
|
|
||||||
type: integer
|
|
||||||
Total-Count:
|
|
||||||
description: Total number of items
|
|
||||||
schema:
|
|
||||||
type: integer
|
|
||||||
Total-Pages:
|
|
||||||
description: Total number of pages
|
|
||||||
schema:
|
|
||||||
type: integer
|
|
||||||
|
|
||||||
created:
|
|
||||||
responses:
|
|
||||||
"201":
|
|
||||||
headers:
|
|
||||||
Location:
|
|
||||||
description: URL of the created resource
|
|
||||||
schema:
|
|
||||||
type: string
|
|
||||||
format: uri
|
|
||||||
content:
|
|
||||||
application/json:
|
|
||||||
schema:
|
|
||||||
$ref: "#/components/schemas/message"
|
|
||||||
|
|
||||||
deferred:
|
|
||||||
responses:
|
|
||||||
"202":
|
|
||||||
headers:
|
|
||||||
Location:
|
|
||||||
description: URL of the created resource
|
|
||||||
schema:
|
|
||||||
type: string
|
|
||||||
format: uri
|
|
||||||
content:
|
|
||||||
application/json:
|
|
||||||
schema:
|
|
||||||
$ref: "#/components/schemas/message"
|
|
||||||
|
|
||||||
validator:
|
|
||||||
responses:
|
|
||||||
"422":
|
|
||||||
description: |
|
|
||||||
This HTTP response is sent when the input data is not valid. It contains an object
|
|
||||||
with all the detected errors.
|
|
||||||
content:
|
|
||||||
application/json:
|
|
||||||
schema:
|
|
||||||
properties:
|
|
||||||
is_valid:
|
|
||||||
type: boolean
|
|
||||||
description: |
|
|
||||||
`true` if the input is valid
|
|
||||||
errors:
|
|
||||||
type: "[string]"
|
|
||||||
nullable: true
|
|
||||||
description: List of global input errors
|
|
||||||
fields:
|
|
||||||
type: object
|
|
||||||
description: |
|
|
||||||
All the fields, with and without errors
|
|
||||||
additionalProperties:
|
|
||||||
properties:
|
|
||||||
is_null:
|
|
||||||
type: boolean
|
|
||||||
description: |
|
|
||||||
`true` if the input value is null
|
|
||||||
is_bound:
|
|
||||||
type: boolean
|
|
||||||
description: |
|
|
||||||
`true` when the value is bound to the form
|
|
||||||
value:
|
|
||||||
type: any
|
|
||||||
description: Item's value; can be any type
|
|
||||||
errors:
|
|
||||||
type: "[string]"
|
|
||||||
nullable: true
|
|
||||||
description: List of errors for this field
|
|
||||||
@ -1,14 +0,0 @@
|
|||||||
---
|
|
||||||
# SPDX-FileCopyrightText: © 2023 Olivier Meunier <olivier@neokraft.net>
|
|
||||||
#
|
|
||||||
# SPDX-License-Identifier: AGPL-3.0-only
|
|
||||||
|
|
||||||
schemas:
|
|
||||||
message:
|
|
||||||
properties:
|
|
||||||
status:
|
|
||||||
type: integer
|
|
||||||
description: HTTP Status Code
|
|
||||||
message:
|
|
||||||
type: string
|
|
||||||
description: Information or error message
|
|
||||||
Loading…
x
Reference in New Issue
Block a user