diff --git a/public/openapi/read.yaml b/public/openapi/read.yaml index 54033e2899..0373bde3b2 100644 --- a/public/openapi/read.yaml +++ b/public/openapi/read.yaml @@ -15,15 +15,17 @@ info: ## Authentication + There are a multitude of ways to authenticate with the Read API. + ### Cookie Authentication This default authentication behaviour of this API is via cookie jar to find a valid session. A valid login session is required for API calls that pertain to operations involving a logged-in user. For example, `/api/unread` is a route showing unread topics, and is not accessible by guest users. - ### Bearer Authentcation + ### Bearer Authentication - The Write API offers bearer authentication, as administered through the administration panel. + Both the Read API and Write API offers bearer authentication, as administered through the administration panel. - * For NodeBB v1.x, this is provided by [`nodebb-plugin-write-api`](https://github.com/NodeBB/nodebb-plugin-write-api). + * For NodeBB v1.x, this is provided by [`nodebb-plugin-write-api`](https://github.com/NodeBB/nodebb-plugin-write-api). The Write API plugin needs to be installed before authentication via bearer token is enabled on routes provided by the Read API. * For NodeBB v2.x+ (in development), the Write API is available in core, and bearer authentication is available out-of-the-box ### JSON Web Token (JWT) @@ -2759,7 +2761,8 @@ paths: get: tags: - home - summary: /api/config + summary: Get forum settings + description: This route retrieves forum settings and user-specific settings for client-side options on the forum. responses: "200": description: "" @@ -2908,7 +2911,8 @@ paths: get: tags: - users - summary: /api/user/uid/{uid} + summary: Get user by uid + description: This route retrieves a user's public profile data. If the calling user is the same as the profile, then it will also return data the user elected to hide (e.g. email/fullname) parameters: - name: uid in: path @@ -2927,7 +2931,8 @@ paths: get: tags: - users - summary: /api/user/username/{username} + summary: Get user by username + description: This route retrieves a user's public profile data. If the calling user is the same as the profile, then it will also return data the user elected to hide (e.g. email/fullname) parameters: - name: username in: path @@ -2946,7 +2951,8 @@ paths: get: tags: - users - summary: /api/user/email/{email} + summary: Get user by email + description: This route retrieves a user's public profile data. If the calling user is the same as the profile, then it will also return data the user elected to hide (e.g. email/fullname) parameters: - name: email in: path @@ -2985,7 +2991,7 @@ paths: get: tags: - users - summary: /api/user/uid/{userslug}/export/uploads + summary: Export a user's uploads (.zip) parameters: - name: userslug in: path @@ -3005,7 +3011,7 @@ paths: get: tags: - users - summary: /api/user/uid/{userslug}/export/profile + summary: Export a user's profile data (.csv) parameters: - name: userslug in: path @@ -3434,456 +3440,11 @@ paths: - 1 - 2 - 3 - "/api/recent/posts/{term?}": - get: - tags: - - topics - summary: /api/recent/posts/{term?} - parameters: - - name: term? - in: path - required: true - schema: - type: string - example: day - responses: - "200": - description: "" - content: - application/json: - schema: - $ref: components/schemas/PostsObject.yaml#/PostsObject - /api/unread/total: - get: - tags: - - topics - summary: Get number of unread topics - responses: - "200": - description: "Success" - content: - text/plain: - schema: - type: number - "/api/topic/teaser/{topic_id}": - get: - tags: - - topics - summary: Get a topic's teaser post - parameters: - - name: topic_id - in: path - required: true - schema: - type: string - example: 1 - responses: - "200": - description: "A JSON object containing the teaser post for a topic" - content: - application/json: - schema: - $ref: components/schemas/PostsObject.yaml#/PostsObject - "/api/topic/pagination/{topic_id}": - get: - tags: - - topics - summary: /api/topic/pagination/{topic_id} - parameters: - - name: topic_id - in: path - required: true - schema: - type: string - example: 1 - responses: - "200": - description: "" - content: - application/json: - schema: - $ref: components/schemas/Pagination.yaml#/Pagination - /api/post/upload: - post: - tags: - - posts - summary: /api/post/upload - responses: - "200": - description: "" - content: - application/json: - schema: - type: array - items: - type: object - properties: - name: - type: string - url: - type: string - text/plain: - schema: - type: array - items: - type: object - properties: - name: - type: string - url: - type: string - "403": - description: "" - content: - application/json: - schema: - type: string - example: Forbidden - text/plain: - schema: - type: string - example: Forbidden - "500": - description: "" - content: - application/json: - schema: - type: object - properties: - path: - type: string - error: - type: string - text/plain: - schema: - type: object - properties: - path: - type: string - error: - type: string - /api/topic/thumb/upload: - post: - tags: - - topics - summary: Upload topic thumb - requestBody: - required: true - content: - multipart/form-data: - schema: - type: object - properties: - files: - type: array - items: - type: string - format: binary - required: - - files - responses: - "200": - description: "Image uploaded" - content: - application/json: - schema: - type: object - properties: - name: - type: string - description: The filename - url: - type: string - description: URL of the uploaded image for use client-side - path: - type: string - description: Path to the file in the local file system - /api/login: - get: - tags: - - authentication - summary: /api/login - responses: - "200": - description: "" - content: - application/json: - schema: - allOf: - - type: object - properties: - loginFormEntry: - type: array - items: - type: object - properties: - label: - type: string - description: A label for the added block - html: - type: string - description: HTML to render on the login page - styleName: - type: string - description: Custom identifier (value is added to `input[id]` and `label[for]`) - alternate_logins: - type: boolean - authentication: - type: array - items: - type: object - properties: - name: - type: string - url: - type: string - callbackURL: - type: string - icon: - type: string - scope: - type: string - prompt: - type: string - allowRegistration: - type: boolean - allowLoginWith: - type: string - title: - type: string - allowPasswordReset: - type: boolean - allowLocalLogin: - type: boolean - - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - - $ref: components/schemas/CommonProps.yaml#/CommonProps - /api/register: - get: - tags: - - authentication - summary: /api/register - responses: - "200": - description: "" - content: - application/json: - schema: - allOf: - - type: object - properties: - register_window:spansize: - type: string - alternate_logins: - type: boolean - authentication: - type: array - items: - type: object - properties: - name: - type: string - url: - type: string - callbackURL: - type: string - icon: - type: string - scope: - type: string - prompt: - type: string - minimumUsernameLength: - type: number - maximumUsernameLength: - type: number - minimumPasswordLength: - type: number - minimumPasswordStrength: - type: number - regFormEntry: - type: array - items: - type: object - properties: - label: - type: string - html: - type: string - styleName: - type: string - title: - type: string - - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - - $ref: components/schemas/CommonProps.yaml#/CommonProps - # /api/register/complete: - # get: - # tags: - # - authentication - # summary: /api/register/complete - # responses: - # "200": - # description: "" - # content: - # application/json: - # schema: - # allOf: - # - type: object - # properties: - # title: - # type: string - # errors: - # type: array - # items: {} - # sections: - # type: array - # items: - # type: string - # - $ref: components/schemas/CommonProps.yaml#/CommonProps - /api/search: - get: - tags: - - search - summary: /api/search - responses: - "200": - description: "" - content: - application/json: - schema: - allOf: - - type: object - properties: - posts: - $ref: components/schemas/PostsObject.yaml#/PostsObject - matchCount: - type: number - pageCount: - type: number - time: - type: string - multiplePages: - type: boolean - search_query: - type: string - term: - type: string - categories: - type: array - items: - type: object - properties: - value: - oneOf: - - type: string - - type: number - text: - type: string - categoriesCount: - type: number - expandSearch: - type: boolean - showAsPosts: - type: boolean - showAsTopics: - type: boolean - title: - type: string - searchDefaultSortBy: - type: string - required: - - posts - - matchCount - - pageCount - - time - - multiplePages - - search_query - - categories - - categoriesCount - - expandSearch - - showAsPosts - - showAsTopics - - title - - searchDefaultSortBy - - $ref: components/schemas/Pagination.yaml#/Pagination - - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - - $ref: components/schemas/CommonProps.yaml#/CommonProps - "/api/reset": - get: - tags: - - authentication - summary: Get user password reset (step 1) - responses: - "200": - description: "A JSON object containing the 1st step of the user password reset flow" - content: - application/json: - schema: - allOf: - - type: object - properties: - code: - type: string - nullable: true - title: - type: string - - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - - $ref: components/schemas/CommonProps.yaml#/CommonProps - "/api/reset/{code}": - get: - tags: - - authentication - summary: Get user password reset (step 2) - parameters: - - name: code - in: path - required: true - schema: - type: string - example: testCode - responses: - "200": - description: "A JSON object containing the 2nd step of the user password reset flow" - content: - application/json: - schema: - allOf: - - type: object - properties: - valid: - type: boolean - code: - type: string - minimumPasswordLength: - type: number - minimumPasswordStrength: - type: number - title: - type: string - - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - - $ref: components/schemas/CommonProps.yaml#/CommonProps - "/api/email/unsubscribe/{token}": - # TODO: Need GET route here as well - post: - tags: - - emails - summary: /api/email/unsubscribe/{token} - parameters: - - name: token - in: path - required: true - schema: - type: string - example: testToken - responses: - "200": - description: "Successfully unsubscribed" - "500": - description: "Server-side error (likely token verification failure)" "/api/topic/{topic_id}/{slug}/{post_index}": get: tags: - topics - summary: /api/topic/{topic_id}/{slug}/{post_index} + summary: Get topic data parameters: - name: topic_id in: path @@ -3892,12 +3453,14 @@ paths: type: string example: 1 - name: slug + description: This parameter is not required. If omitted, the request will be automatically redirected with the proper topic slug. in: path required: true schema: type: string example: test-topic - name: post_index + description: This parameter is not required. If omitted, the request will presume that you want the first post. The API response is largely unaffected by this parameter, it is used client-side (to send the user to the requested post), and changes the meta/link tags in the server-side generated HTML. in: path required: true schema: @@ -4280,11 +3843,455 @@ paths: - $ref: components/schemas/Pagination.yaml#/Pagination - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - $ref: components/schemas/CommonProps.yaml#/CommonProps - "/api/topic/{topic_id}/{slug}": + /api/recent: get: tags: - topics - summary: /api/topic/{topic_id}/{slug} + summary: Get recent topics + description: Returns a list of topics sorted by timestamp. + responses: + "200": + description: An array of topic objects sorted by timestamp. + content: + application/json: + schema: + allOf: + - type: object + properties: + nextStart: + type: number + topicCount: + type: number + topics: + type: array + items: + $ref: components/schemas/TopicObject.yaml#/TopicObject + tids: + type: array + items: + type: number + canPost: + type: boolean + categories: + type: array + items: + type: object + properties: + cid: + type: number + description: A category identifier + name: + type: string + level: + type: string + icon: + type: string + parentCid: + type: number + description: The category identifier for the category that is the immediate + ancestor of the current category + color: + type: string + bgColor: + type: string + selected: + type: boolean + imageClass: + type: string + allCategoriesUrl: + type: string + selectedCategory: + type: object + properties: + icon: + type: string + name: + type: string + bgColor: + type: string + nullable: true + selectedCids: + type: array + items: + type: number + feeds:disableRSS: + type: number + rssFeedUrl: + type: string + title: + type: string + filters: + type: array + items: + type: object + properties: + name: + type: string + url: + type: string + selected: + type: boolean + filter: + type: string + selectedFilter: + type: object + properties: + name: + type: string + url: + type: string + selected: + type: boolean + filter: + type: string + terms: + type: array + items: + type: object + properties: + name: + type: string + url: + type: string + selected: + type: boolean + term: + type: string + selectedTerm: + type: object + properties: + name: + type: string + url: + type: string + selected: + type: boolean + term: + type: string + - $ref: components/schemas/Pagination.yaml#/Pagination + - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs + - $ref: components/schemas/CommonProps.yaml#/CommonProps + "/api/recent/posts/{term}": + get: + tags: + - posts + summary: Get recent posts + parameters: + - name: term + in: path + required: true + schema: + type: string + example: daily + responses: + "200": + description: "" + content: + application/json: + schema: + $ref: components/schemas/PostsObject.yaml#/PostsObject + /api/unread: + get: + tags: + - topics + summary: Get unread topics + description: Returns a list of the current user's unread topics, sorted by the + last post's timestamp. + responses: + "200": + description: An array of unread topic objects sorted by the last post's timestamp. + content: + application/json: + schema: + allOf: + - type: object + properties: + showSelect: + type: boolean + nextStart: + type: number + topics: + type: array + items: + type: object + properties: + tid: + type: number + description: A topic identifier + uid: + type: number + description: A user identifier + cid: + type: number + description: A category identifier + mainPid: + type: number + description: The post id of the first post in this topic (also called the + "original post") + title: + type: string + slug: + type: string + timestamp: + type: number + lastposttime: + type: number + postcount: + type: number + viewcount: + type: number + teaserPid: + type: number + upvotes: + type: number + downvotes: + type: number + deleted: + type: number + locked: + type: number + pinned: + type: number + description: Whether or not this particular topic is pinned to the top of the + category + titleRaw: + type: string + timestampISO: + type: string + description: An ISO 8601 formatted date string (complementing `timestamp`) + lastposttimeISO: + type: string + votes: + type: number + category: + type: object + properties: + cid: + type: number + description: A category identifier + name: + type: string + slug: + type: string + icon: + type: string + image: + nullable: true + imageClass: + nullable: true + type: string + bgColor: + type: string + color: + type: string + disabled: + type: number + user: + type: object + properties: + uid: + type: number + description: A user identifier + username: + type: string + description: A friendly name for a given user account + fullname: + type: string + userslug: + type: string + description: An URL-safe variant of the username (i.e. lower-cased, spaces + removed, etc.) + reputation: + type: number + postcount: + type: number + picture: + nullable: true + type: string + signature: + nullable: true + type: string + banned: + type: number + status: + type: string + icon:text: + type: string + description: A single-letter representation of a username. This is used in the + auto-generated icon given to users without + an avatar + icon:bgColor: + type: string + description: A six-character hexadecimal colour code assigned to the user. This + value is used in conjunction with + `icon:text` for the user's auto-generated + icon + example: "#f44336" + banned_until_readable: + type: string + teaser: + type: object + properties: + pid: + type: number + uid: + type: number + description: A user identifier + timestamp: + type: number + tid: + type: number + description: A topic identifier + content: + type: string + timestampISO: + type: string + description: An ISO 8601 formatted date string (complementing `timestamp`) + user: + type: object + properties: + uid: + type: number + description: A user identifier + username: + type: string + description: A friendly name for a given user account + userslug: + type: string + description: An URL-safe variant of the username (i.e. lower-cased, spaces + removed, etc.) + picture: + nullable: true + type: string + icon:text: + type: string + description: A single-letter representation of a username. This is used in the + auto-generated icon given to users + without an avatar + icon:bgColor: + type: string + description: A six-character hexadecimal colour code assigned to the user. This + value is used in conjunction with + `icon:text` for the user's + auto-generated icon + example: "#f44336" + index: + type: number + tags: + type: array + items: + type: object + properties: + value: + type: string + valueEscaped: + type: string + color: + type: string + bgColor: + type: string + score: + type: number + isOwner: + type: boolean + ignored: + type: boolean + unread: + type: boolean + bookmark: + nullable: true + unreplied: + type: boolean + icons: + type: array + items: + type: string + index: + type: number + isQuestion: + nullable: true + topicCount: + type: number + title: + type: string + pageCount: + type: number + categories: + type: array + items: + type: object + properties: + cid: + type: number + description: A category identifier + name: + type: string + level: + type: string + icon: + type: string + parentCid: + type: number + description: The category identifier for the category that is the immediate + ancestor of the current category + color: + type: string + bgColor: + type: string + selected: + type: boolean + imageClass: + type: string + allCategoriesUrl: + type: string + selectedCids: + type: array + items: + type: number + filters: + type: array + items: + type: object + properties: + name: + type: string + url: + type: string + selected: + type: boolean + filter: + type: string + selectedFilter: + type: object + properties: + name: + type: string + url: + type: string + selected: + type: boolean + filter: + type: string + - $ref: components/schemas/Pagination.yaml#/Pagination + - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs + - $ref: components/schemas/CommonProps.yaml#/CommonProps + /api/unread/total: + get: + tags: + - topics + summary: Get number of unread topics + responses: + "200": + description: "Success" + content: + text/plain: + schema: + type: number + "/api/topic/teaser/{topic_id}": + get: + tags: + - topics + summary: Get a topic's teaser post parameters: - name: topic_id in: path @@ -4292,15 +4299,410 @@ paths: schema: type: string example: 1 - - name: slug + responses: + "200": + description: "A JSON object containing the teaser post for a topic" + content: + application/json: + schema: + $ref: components/schemas/PostsObject.yaml#/PostsObject + "/api/topic/pagination/{topic_id}": + get: + tags: + - topics + summary: Get topic pagination data + description: This route retrieves pagination data for a given topic. It is used mainly client-side, as it return data necessary to update a pagination block client-side. + parameters: + - name: topic_id in: path required: true schema: type: string - example: '' + example: 1 responses: - "418": - description: "TODO: A proper response needs to be added. It is not really a teapot | Copy response from the route w/o post_index" + "200": + description: "" + content: + application/json: + schema: + $ref: components/schemas/Pagination.yaml#/Pagination + /api/post/upload: + post: + tags: + - posts + summary: Upload a file to a specific post + description: Provided by NodeBB core and used mainly by the composer, this route allows you to upload an image or file to a post. + responses: + "200": + description: "" + content: + application/json: + schema: + type: array + items: + type: object + properties: + name: + type: string + url: + type: string + text/plain: + schema: + type: array + items: + type: object + properties: + name: + type: string + url: + type: string + "403": + description: "" + content: + application/json: + schema: + type: string + example: Forbidden + text/plain: + schema: + type: string + example: Forbidden + "500": + description: "" + content: + application/json: + schema: + type: object + properties: + path: + type: string + error: + type: string + text/plain: + schema: + type: object + properties: + path: + type: string + error: + type: string + /api/topic/thumb/upload: + post: + tags: + - topics + summary: Upload topic thumb + requestBody: + required: true + content: + multipart/form-data: + schema: + type: object + properties: + files: + type: array + items: + type: string + format: binary + required: + - files + responses: + "200": + description: "Image uploaded" + content: + application/json: + schema: + type: object + properties: + name: + type: string + description: The filename + url: + type: string + description: URL of the uploaded image for use client-side + path: + type: string + description: Path to the file in the local file system + /api/login: + get: + tags: + - authentication + summary: /api/login + responses: + "200": + description: "" + content: + application/json: + schema: + allOf: + - type: object + properties: + loginFormEntry: + type: array + items: + type: object + properties: + label: + type: string + description: A label for the added block + html: + type: string + description: HTML to render on the login page + styleName: + type: string + description: Custom identifier (value is added to `input[id]` and `label[for]`) + alternate_logins: + type: boolean + authentication: + type: array + items: + type: object + properties: + name: + type: string + url: + type: string + callbackURL: + type: string + icon: + type: string + scope: + type: string + prompt: + type: string + allowRegistration: + type: boolean + allowLoginWith: + type: string + title: + type: string + allowPasswordReset: + type: boolean + allowLocalLogin: + type: boolean + - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs + - $ref: components/schemas/CommonProps.yaml#/CommonProps + /api/register: + get: + tags: + - authentication + summary: /api/register + responses: + "200": + description: "" + content: + application/json: + schema: + allOf: + - type: object + properties: + register_window:spansize: + type: string + alternate_logins: + type: boolean + authentication: + type: array + items: + type: object + properties: + name: + type: string + url: + type: string + callbackURL: + type: string + icon: + type: string + scope: + type: string + prompt: + type: string + minimumUsernameLength: + type: number + maximumUsernameLength: + type: number + minimumPasswordLength: + type: number + minimumPasswordStrength: + type: number + regFormEntry: + type: array + items: + type: object + properties: + label: + type: string + html: + type: string + styleName: + type: string + title: + type: string + - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs + - $ref: components/schemas/CommonProps.yaml#/CommonProps + # /api/register/complete: + # get: + # tags: + # - authentication + # summary: /api/register/complete + # responses: + # "200": + # description: "" + # content: + # application/json: + # schema: + # allOf: + # - type: object + # properties: + # title: + # type: string + # errors: + # type: array + # items: {} + # sections: + # type: array + # items: + # type: string + # - $ref: components/schemas/CommonProps.yaml#/CommonProps + /api/search: + get: + tags: + - search + summary: /api/search + responses: + "200": + description: "" + content: + application/json: + schema: + allOf: + - type: object + properties: + posts: + $ref: components/schemas/PostsObject.yaml#/PostsObject + matchCount: + type: number + pageCount: + type: number + time: + type: string + multiplePages: + type: boolean + search_query: + type: string + term: + type: string + categories: + type: array + items: + type: object + properties: + value: + oneOf: + - type: string + - type: number + text: + type: string + categoriesCount: + type: number + expandSearch: + type: boolean + showAsPosts: + type: boolean + showAsTopics: + type: boolean + title: + type: string + searchDefaultSortBy: + type: string + required: + - posts + - matchCount + - pageCount + - time + - multiplePages + - search_query + - categories + - categoriesCount + - expandSearch + - showAsPosts + - showAsTopics + - title + - searchDefaultSortBy + - $ref: components/schemas/Pagination.yaml#/Pagination + - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs + - $ref: components/schemas/CommonProps.yaml#/CommonProps + "/api/reset": + get: + tags: + - authentication + summary: Get user password reset (step 1) + responses: + "200": + description: "A JSON object containing the 1st step of the user password reset flow" + content: + application/json: + schema: + allOf: + - type: object + properties: + code: + type: string + nullable: true + title: + type: string + - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs + - $ref: components/schemas/CommonProps.yaml#/CommonProps + "/api/reset/{code}": + get: + tags: + - authentication + summary: Get user password reset (step 2) + parameters: + - name: code + in: path + required: true + schema: + type: string + example: testCode + responses: + "200": + description: "A JSON object containing the 2nd step of the user password reset flow" + content: + application/json: + schema: + allOf: + - type: object + properties: + valid: + type: boolean + code: + type: string + minimumPasswordLength: + type: number + minimumPasswordStrength: + type: number + title: + type: string + - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs + - $ref: components/schemas/CommonProps.yaml#/CommonProps + "/api/email/unsubscribe/{token}": + # TODO: Need GET route here as well + post: + tags: + - emails + summary: /api/email/unsubscribe/{token} + parameters: + - name: token + in: path + required: true + schema: + type: string + example: testToken + responses: + "200": + description: "Successfully unsubscribed" + "500": + description: "Server-side error (likely token verification failure)" "/api/post/{pid}": get: tags: @@ -5089,7 +5491,7 @@ paths: get: tags: - topics - summary: Get Popular Topics + summary: Get popular topics description: Returns a list of topics sorted by most replies. In an event of a tie breaker, the topic with the most views. Can be filtered by All Time, Day, Week, or Month. @@ -5215,139 +5617,11 @@ paths: - $ref: components/schemas/Pagination.yaml#/Pagination - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - $ref: components/schemas/CommonProps.yaml#/CommonProps - /api/recent: - get: - tags: - - topics - summary: Recent Topics - description: Returns a list of topics sorted by timestamp. - responses: - "200": - description: An array of topic objects sorted by timestamp. - content: - application/json: - schema: - allOf: - - type: object - properties: - nextStart: - type: number - topicCount: - type: number - topics: - type: array - items: - $ref: components/schemas/TopicObject.yaml#/TopicObject - tids: - type: array - items: - type: number - canPost: - type: boolean - categories: - type: array - items: - type: object - properties: - cid: - type: number - description: A category identifier - name: - type: string - level: - type: string - icon: - type: string - parentCid: - type: number - description: The category identifier for the category that is the immediate - ancestor of the current category - color: - type: string - bgColor: - type: string - selected: - type: boolean - imageClass: - type: string - allCategoriesUrl: - type: string - selectedCategory: - type: object - properties: - icon: - type: string - name: - type: string - bgColor: - type: string - nullable: true - selectedCids: - type: array - items: - type: number - feeds:disableRSS: - type: number - rssFeedUrl: - type: string - title: - type: string - filters: - type: array - items: - type: object - properties: - name: - type: string - url: - type: string - selected: - type: boolean - filter: - type: string - selectedFilter: - type: object - properties: - name: - type: string - url: - type: string - selected: - type: boolean - filter: - type: string - terms: - type: array - items: - type: object - properties: - name: - type: string - url: - type: string - selected: - type: boolean - term: - type: string - selectedTerm: - type: object - properties: - name: - type: string - url: - type: string - selected: - type: boolean - term: - type: string - - $ref: components/schemas/Pagination.yaml#/Pagination - - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - - $ref: components/schemas/CommonProps.yaml#/CommonProps /api/top: get: tags: - topics - summary: Top Topics + summary: Get top topics description: Returns a list of topics sorted by most upvotes. responses: "200": @@ -5484,296 +5758,12 @@ paths: - $ref: components/schemas/Pagination.yaml#/Pagination - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - $ref: components/schemas/CommonProps.yaml#/CommonProps - /api/unread: - get: - tags: - - topics - summary: Unread Topics - description: Returns a list of the current user's unread topics, sorted by the - last post's timestamp. - responses: - "200": - description: An array of unread topic objects sorted by the last post's timestamp. - content: - application/json: - schema: - allOf: - - type: object - properties: - showSelect: - type: boolean - nextStart: - type: number - topics: - type: array - items: - type: object - properties: - tid: - type: number - description: A topic identifier - uid: - type: number - description: A user identifier - cid: - type: number - description: A category identifier - mainPid: - type: number - description: The post id of the first post in this topic (also called the - "original post") - title: - type: string - slug: - type: string - timestamp: - type: number - lastposttime: - type: number - postcount: - type: number - viewcount: - type: number - teaserPid: - type: number - upvotes: - type: number - downvotes: - type: number - deleted: - type: number - locked: - type: number - pinned: - type: number - description: Whether or not this particular topic is pinned to the top of the - category - titleRaw: - type: string - timestampISO: - type: string - description: An ISO 8601 formatted date string (complementing `timestamp`) - lastposttimeISO: - type: string - votes: - type: number - category: - type: object - properties: - cid: - type: number - description: A category identifier - name: - type: string - slug: - type: string - icon: - type: string - image: - nullable: true - imageClass: - nullable: true - type: string - bgColor: - type: string - color: - type: string - disabled: - type: number - user: - type: object - properties: - uid: - type: number - description: A user identifier - username: - type: string - description: A friendly name for a given user account - fullname: - type: string - userslug: - type: string - description: An URL-safe variant of the username (i.e. lower-cased, spaces - removed, etc.) - reputation: - type: number - postcount: - type: number - picture: - nullable: true - type: string - signature: - nullable: true - type: string - banned: - type: number - status: - type: string - icon:text: - type: string - description: A single-letter representation of a username. This is used in the - auto-generated icon given to users without - an avatar - icon:bgColor: - type: string - description: A six-character hexadecimal colour code assigned to the user. This - value is used in conjunction with - `icon:text` for the user's auto-generated - icon - example: "#f44336" - banned_until_readable: - type: string - teaser: - type: object - properties: - pid: - type: number - uid: - type: number - description: A user identifier - timestamp: - type: number - tid: - type: number - description: A topic identifier - content: - type: string - timestampISO: - type: string - description: An ISO 8601 formatted date string (complementing `timestamp`) - user: - type: object - properties: - uid: - type: number - description: A user identifier - username: - type: string - description: A friendly name for a given user account - userslug: - type: string - description: An URL-safe variant of the username (i.e. lower-cased, spaces - removed, etc.) - picture: - nullable: true - type: string - icon:text: - type: string - description: A single-letter representation of a username. This is used in the - auto-generated icon given to users - without an avatar - icon:bgColor: - type: string - description: A six-character hexadecimal colour code assigned to the user. This - value is used in conjunction with - `icon:text` for the user's - auto-generated icon - example: "#f44336" - index: - type: number - tags: - type: array - items: - type: object - properties: - value: - type: string - valueEscaped: - type: string - color: - type: string - bgColor: - type: string - score: - type: number - isOwner: - type: boolean - ignored: - type: boolean - unread: - type: boolean - bookmark: - nullable: true - unreplied: - type: boolean - icons: - type: array - items: - type: string - index: - type: number - isQuestion: - nullable: true - topicCount: - type: number - title: - type: string - pageCount: - type: number - categories: - type: array - items: - type: object - properties: - cid: - type: number - description: A category identifier - name: - type: string - level: - type: string - icon: - type: string - parentCid: - type: number - description: The category identifier for the category that is the immediate - ancestor of the current category - color: - type: string - bgColor: - type: string - selected: - type: boolean - imageClass: - type: string - allCategoriesUrl: - type: string - selectedCids: - type: array - items: - type: number - filters: - type: array - items: - type: object - properties: - name: - type: string - url: - type: string - selected: - type: boolean - filter: - type: string - selectedFilter: - type: object - properties: - name: - type: string - url: - type: string - selected: - type: boolean - filter: - type: string - - $ref: components/schemas/Pagination.yaml#/Pagination - - $ref: components/schemas/Breadcrumbs.yaml#/Breadcrumbs - - $ref: components/schemas/CommonProps.yaml#/CommonProps "/api/category/{category_id}/{slug}/{topic_index}": get: tags: - categories - summary: /api/category/{category_id}/{slug}/{topic_index} + summary: Get a single category + description: This route retrieves a single category's data, along with its children and the topics created inside of the category. parameters: - name: category_id in: path @@ -5782,12 +5772,14 @@ paths: type: string example: 1 - name: slug + description: This parameter is not required. If omitted, the request will be automatically redirected with the proper category slug. in: path required: true schema: type: string example: test - name: topic_index + description: This parameter is not required. If omitted, the request will presume that you want the first post. The API response is largely unaffected by this parameter, it is used client-side (to send the user to the requested post), and changes the meta/link tags in the server-side generated HTML. in: path required: true schema: @@ -6248,7 +6240,7 @@ paths: get: tags: - users - summary: /api/user/{userslug}/posts + summary: Get a user's posts parameters: - name: userslug in: path @@ -6294,7 +6286,7 @@ paths: get: tags: - users - summary: /api/user/{userslug}/topics + summary: Get a user's topics parameters: - name: userslug in: path @@ -6342,7 +6334,7 @@ paths: get: tags: - users - summary: /api/user/{userslug}/best + summary: Get a user's best performing topics parameters: - name: userslug in: path @@ -6388,7 +6380,7 @@ paths: get: tags: - users - summary: /api/user/{userslug}/groups + summary: Get user's groups parameters: - name: userslug in: path