diff --git a/Sources/ReadeckAPI/bookmarks/routes.yaml b/Sources/ReadeckAPI/bookmarks/routes.yaml deleted file mode 100644 index 8f2f929..0000000 --- a/Sources/ReadeckAPI/bookmarks/routes.yaml +++ /dev/null @@ -1,563 +0,0 @@ ---- -# SPDX-FileCopyrightText: © 2023 Olivier Meunier -# -# 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" diff --git a/Sources/ReadeckAPI/bookmarks/traits.yaml b/Sources/ReadeckAPI/bookmarks/traits.yaml deleted file mode 100644 index 07c434e..0000000 --- a/Sources/ReadeckAPI/bookmarks/traits.yaml +++ /dev/null @@ -1,27 +0,0 @@ ---- -# SPDX-FileCopyrightText: © 2024 Olivier Meunier -# -# 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 diff --git a/Sources/ReadeckAPI/bookmarks/types.yaml b/Sources/ReadeckAPI/bookmarks/types.yaml deleted file mode 100644 index cf12fa2..0000000 --- a/Sources/ReadeckAPI/bookmarks/types.yaml +++ /dev/null @@ -1,580 +0,0 @@ ---- -# SPDX-FileCopyrightText: © 2023 Olivier Meunier -# -# 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 diff --git a/Sources/ReadeckAPI/cookbook/routes.yaml b/Sources/ReadeckAPI/cookbook/routes.yaml deleted file mode 100644 index 74e1f96..0000000 --- a/Sources/ReadeckAPI/cookbook/routes.yaml +++ /dev/null @@ -1,145 +0,0 @@ ---- -# SPDX-FileCopyrightText: © 2023 Olivier Meunier -# -# 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 diff --git a/Sources/ReadeckAPI/open_api.yaml b/Sources/ReadeckAPI/open_api.yaml deleted file mode 100644 index 9a6219f..0000000 --- a/Sources/ReadeckAPI/open_api.yaml +++ /dev/null @@ -1,339 +0,0 @@ ---- -# SPDX-FileCopyrightText: © 2023 Olivier Meunier -# -# 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 " __BASE_URI__/bookmarks - ``` - - Or, in NodeJS: - - ```js - fetch("__BASE_URI__/bookmarks", { - headers: { - "Authorization": "Bearer ", - }, - }) - ``` - - ## 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" diff --git a/Sources/ReadeckAPI/profile/routes.yaml b/Sources/ReadeckAPI/profile/routes.yaml deleted file mode 100644 index 3517159..0000000 --- a/Sources/ReadeckAPI/profile/routes.yaml +++ /dev/null @@ -1,55 +0,0 @@ ---- -# SPDX-FileCopyrightText: © 2023 Olivier Meunier -# -# 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" diff --git a/Sources/ReadeckAPI/profile/types.yaml b/Sources/ReadeckAPI/profile/types.yaml deleted file mode 100644 index ccc0617..0000000 --- a/Sources/ReadeckAPI/profile/types.yaml +++ /dev/null @@ -1,143 +0,0 @@ ---- -# SPDX-FileCopyrightText: © 2023 Olivier Meunier -# -# 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 - } - } - } - } diff --git a/Sources/ReadeckAPI/traits.yaml b/Sources/ReadeckAPI/traits.yaml deleted file mode 100644 index 238590c..0000000 --- a/Sources/ReadeckAPI/traits.yaml +++ /dev/null @@ -1,125 +0,0 @@ ---- -# SPDX-FileCopyrightText: © 2023 Olivier Meunier -# -# 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 diff --git a/Sources/ReadeckAPI/types.yaml b/Sources/ReadeckAPI/types.yaml deleted file mode 100644 index a4ab7e0..0000000 --- a/Sources/ReadeckAPI/types.yaml +++ /dev/null @@ -1,14 +0,0 @@ ---- -# SPDX-FileCopyrightText: © 2023 Olivier Meunier -# -# 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 diff --git a/Swift b/Swift new file mode 100644 index 0000000..e69de29 diff --git a/readeck-api.yaml b/readeck-api.yaml deleted file mode 100644 index 9a6219f..0000000 --- a/readeck-api.yaml +++ /dev/null @@ -1,339 +0,0 @@ ---- -# SPDX-FileCopyrightText: © 2023 Olivier Meunier -# -# 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 " __BASE_URI__/bookmarks - ``` - - Or, in NodeJS: - - ```js - fetch("__BASE_URI__/bookmarks", { - headers: { - "Authorization": "Bearer ", - }, - }) - ``` - - ## 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" diff --git a/readeck_api/api.yaml b/readeck_api/api.yaml deleted file mode 100644 index 9a6219f..0000000 --- a/readeck_api/api.yaml +++ /dev/null @@ -1,339 +0,0 @@ ---- -# SPDX-FileCopyrightText: © 2023 Olivier Meunier -# -# 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 " __BASE_URI__/bookmarks - ``` - - Or, in NodeJS: - - ```js - fetch("__BASE_URI__/bookmarks", { - headers: { - "Authorization": "Bearer ", - }, - }) - ``` - - ## 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" diff --git a/readeck_api/bookmarks/routes.yaml b/readeck_api/bookmarks/routes.yaml deleted file mode 100644 index 8f2f929..0000000 --- a/readeck_api/bookmarks/routes.yaml +++ /dev/null @@ -1,563 +0,0 @@ ---- -# SPDX-FileCopyrightText: © 2023 Olivier Meunier -# -# 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" diff --git a/readeck_api/bookmarks/traits.yaml b/readeck_api/bookmarks/traits.yaml deleted file mode 100644 index 07c434e..0000000 --- a/readeck_api/bookmarks/traits.yaml +++ /dev/null @@ -1,27 +0,0 @@ ---- -# SPDX-FileCopyrightText: © 2024 Olivier Meunier -# -# 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 diff --git a/readeck_api/bookmarks/types.yaml b/readeck_api/bookmarks/types.yaml deleted file mode 100644 index cf12fa2..0000000 --- a/readeck_api/bookmarks/types.yaml +++ /dev/null @@ -1,580 +0,0 @@ ---- -# SPDX-FileCopyrightText: © 2023 Olivier Meunier -# -# 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 diff --git a/readeck_api/cookbook/routes.yaml b/readeck_api/cookbook/routes.yaml deleted file mode 100644 index 74e1f96..0000000 --- a/readeck_api/cookbook/routes.yaml +++ /dev/null @@ -1,145 +0,0 @@ ---- -# SPDX-FileCopyrightText: © 2023 Olivier Meunier -# -# 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 diff --git a/readeck_api/profile/routes.yaml b/readeck_api/profile/routes.yaml deleted file mode 100644 index 3517159..0000000 --- a/readeck_api/profile/routes.yaml +++ /dev/null @@ -1,55 +0,0 @@ ---- -# SPDX-FileCopyrightText: © 2023 Olivier Meunier -# -# 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" diff --git a/readeck_api/profile/types.yaml b/readeck_api/profile/types.yaml deleted file mode 100644 index ccc0617..0000000 --- a/readeck_api/profile/types.yaml +++ /dev/null @@ -1,143 +0,0 @@ ---- -# SPDX-FileCopyrightText: © 2023 Olivier Meunier -# -# 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 - } - } - } - } diff --git a/readeck_api/traits.yaml b/readeck_api/traits.yaml deleted file mode 100644 index 238590c..0000000 --- a/readeck_api/traits.yaml +++ /dev/null @@ -1,125 +0,0 @@ ---- -# SPDX-FileCopyrightText: © 2023 Olivier Meunier -# -# 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 diff --git a/readeck_api/types.yaml b/readeck_api/types.yaml deleted file mode 100644 index a4ab7e0..0000000 --- a/readeck_api/types.yaml +++ /dev/null @@ -1,14 +0,0 @@ ---- -# SPDX-FileCopyrightText: © 2023 Olivier Meunier -# -# 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