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