Last active
January 27, 2021 11:08
-
-
Save JuliusNM/6a6940abd73e57a46aa3af02eb6ce8a4 to your computer and use it in GitHub Desktop.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
openapi: 3.0.0 | |
info: | |
title: NodeBB Read API | |
version: 1.15.0 | |
contact: | |
email: support@nodebb.org | |
license: | |
name: GPL-3.0 | |
description: >- | |
# Overview | |
The following document outlines every Read API route available via NodeBB. Unlike the write API, the v1.x API was coded organically, and is **not** strictly RESTful. These shortcomings will be addressed in time as the APIs mature. | |
## Shortcomings | |
The Read API is named because its primary use is by NodeBB itself when navigating between pages. Therefore, the routes almost universally always follow the same path as actual pages on NodeBB itself. There are also a small number of non-`GET` routes, which doesn't necessarily make sense in a Read API. These will be merged into the Write API in time. | |
## 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 Authentication | |
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). 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 | |
tags: | |
- name: home | |
description: Routes used at the forum index only | |
- name: categories | |
description: Category hierarchy and navigation | |
- name: topics | |
- name: posts | |
- name: users | |
- name: authentication | |
description: User authentication (e.g. login/registration) | |
- name: groups | |
description: User groups | |
- name: admin | |
description: Administrative Control Panel (ACP) routing | |
- name: emails | |
description: Email utilities | |
- name: flags | |
description: Reporting of content by users | |
- name: notifications | |
description: Real-time notifications | |
- name: search | |
- name: tags | |
description: Disparate method of categorizing topics | |
- name: shorthand | |
description: Convenience and utility routes for accessing other part of the API | |
- name: other | |
description: Other one-off routes that do not fit in a section of their own | |
paths: | |
/api/: | |
$ref: 'read/index.yaml' | |
/api/admin: | |
$ref: 'read/admin.yaml' | |
/api/admin/dashboard: | |
$ref: 'read/admin/dashboard.yaml' | |
"/api/admin/settings/{term}": | |
$ref: 'read/admin/settings/term.yaml' | |
/api/admin/settings/languages: | |
$ref: 'read/admin/settings/languages.yaml' | |
/api/admin/settings/navigation: | |
$ref: 'read/admin/settings/navigation.yaml' | |
/api/admin/settings/homepage: | |
$ref: 'read/admin/settings/homepage.yaml' | |
/api/admin/settings/social: | |
$ref: 'read/admin/settings/social.yaml' | |
/api/admin/settings/email: | |
$ref: 'read/admin/settings/email.yaml' | |
/api/admin/settings/user: | |
$ref: 'read/admin/settings/user.yaml' | |
/api/admin/settings/post: | |
$ref: 'read/admin/settings/post.yaml' | |
/api/admin/manage/categories: | |
$ref: 'read/admin/manage/categories.yaml' | |
"/api/admin/manage/categories/{category_id}": | |
$ref: 'read/admin/manage/categories/category_id.yaml' | |
"/api/admin/manage/categories/{category_id}/analytics": | |
$ref: 'read/admin/manage/categories/category_id/analytics.yaml' | |
"/api/admin/manage/privileges/{cid}": | |
$ref: 'read/admin/manage/privileges/cid.yaml' | |
/api/admin/manage/tags: | |
$ref: 'read/admin/manage/tags.yaml' | |
/api/admin/manage/users: | |
$ref: 'read/admin/manage/users.yaml' | |
/api/admin/manage/registration: | |
$ref: 'read/admin/manage/registration.yaml' | |
/api/admin/manage/admins-mods: | |
$ref: 'read/admin/manage/admins-mods.yaml' | |
/api/admin/manage/groups: | |
$ref: 'read/admin/manage/groups.yaml' | |
"/api/admin/manage/groups/{name}": | |
$ref: 'read/admin/manage/groups/name.yaml' | |
/api/admin/manage/uploads: | |
$ref: 'read/admin/manage/uploads.yaml' | |
/api/admin/manage/digest: | |
$ref: 'read/admin/manage/digest.yaml' | |
"/api/admin/appearance/{term}": | |
$ref: 'read/admin/appearance/term.yaml' | |
/api/admin/extend/plugins: | |
$ref: 'read/admin/extend/plugins.yaml' | |
/api/admin/extend/widgets: | |
$ref: 'read/admin/extend/widgets.yaml' | |
/api/admin/extend/rewards: | |
$ref: 'read/admin/extend/rewards.yaml' | |
/api/admin/advanced/database: | |
$ref: 'read/admin/advanced/database.yaml' | |
/api/admin/advanced/events: | |
$ref: 'read/admin/advanced/events.yaml' | |
/api/admin/advanced/hooks: | |
$ref: 'read/admin/advanced/hooks.yaml' | |
/api/admin/advanced/logs: | |
$ref: 'read/admin/advanced/logs.yaml' | |
/api/admin/advanced/errors: | |
$ref: 'read/admin/advanced/errors.yaml' | |
/api/admin/advanced/errors/export: | |
$ref: 'read/admin/advanced/errors/export.yaml' | |
/api/admin/advanced/cache: | |
$ref: 'read/admin/advanced/cache.yaml' | |
/api/admin/advanced/cache/dump: | |
$ref: 'read/admin/advanced/cache/dump.yaml' | |
/api/admin/development/logger: | |
$ref: 'read/admin/development/logger.yaml' | |
/api/admin/development/info: | |
$ref: 'read/admin/development/info.yaml' | |
/api/admin/users/csv: | |
$ref: 'read/admin/users/csv.yaml' | |
/api/admin/groups/{groupname}/csv: | |
$ref: 'read/admin/groups/groupname/csv.yaml' | |
/api/admin/analytics: | |
$ref: 'read/admin/analytics.yaml' | |
/api/admin/category/uploadpicture: | |
$ref: 'read/admin/category/uploadpicture.yaml' | |
/api/admin/uploadfavicon: | |
$ref: 'read/admin/uploadfavicon.yaml' | |
/api/admin/uploadTouchIcon: | |
$ref: 'read/admin/uploadTouchIcon.yaml' | |
/api/admin/uploadMaskableIcon: | |
$ref: 'read/admin/uploadMaskableIcon.yaml' | |
/api/admin/uploadlogo: | |
$ref: 'read/admin/uploadlogo.yaml' | |
/api/admin/uploadOgImage: | |
$ref: 'read/admin/uploadOgImage.yaml' | |
/api/admin/upload/file: | |
$ref: 'read/admin/upload/file.yaml' | |
/api/admin/uploadDefaultAvatar: | |
$ref: 'read/admin/uploadDefaultAvatar.yaml' | |
/api/config: | |
$ref: 'read/config.yaml' | |
/api/users: | |
$ref: 'read/users.yaml' | |
"/api/user/uid/{uid}": | |
$ref: 'read/user/uid/uid.yaml' | |
"/api/user/username/{username}": | |
$ref: 'read/user/username/username.yaml' | |
"/api/user/email/{email}": | |
$ref: 'read/user/email/email.yaml' | |
"/api/user/uid/{userslug}/export/posts": | |
$ref: 'read/user/uid/userslug/export/posts.yaml' | |
"/api/user/uid/{userslug}/export/uploads": | |
$ref: 'read/user/uid/userslug/export/uploads.yaml' | |
"/api/user/uid/{userslug}/export/profile": | |
$ref: 'read/user/uid/userslug/export/profile.yaml' | |
"/api/{type}/pid/{id}": | |
$ref: 'read/post/pid/id.yaml' | |
"/api/{type}/tid/{id}": | |
$ref: 'read/topic/tid/id.yaml' | |
"/api/{type}/cid/{id}": | |
$ref: 'read/category/cid/id.yaml' | |
/api/categories: | |
$ref: 'read/categories.yaml' | |
"/api/categories/{cid}/moderators": | |
$ref: 'read/categories/cid/moderators.yaml' | |
"/api/topic/{topic_id}/{slug}": | |
$ref: 'read/topic/topic_id.yaml' | |
"/api/topic/{topic_id}/{slug}/{post_index}": | |
$ref: 'read/topic/topic_id.yaml' | |
/api/recent: | |
$ref: 'read/recent.yaml' | |
"/api/recent/posts/{term}": | |
$ref: 'read/recent/posts/term.yaml' | |
/api/unread: | |
$ref: 'read/unread.yaml' | |
/api/unread/total: | |
$ref: 'read/unread/total.yaml' | |
"/api/topic/teaser/{topic_id}": | |
$ref: 'read/topic/teaser/topic_id.yaml' | |
"/api/topic/pagination/{topic_id}": | |
$ref: 'read/topic/pagination/topic_id.yaml' | |
/api/post/upload: | |
$ref: 'read/post/upload.yaml' | |
/api/topic/thumb/upload: | |
$ref: 'read/topic/thumb/upload.yaml' | |
/api/login: | |
$ref: 'read/login.yaml' | |
/api/register: | |
$ref: 'read/register.yaml' | |
/api/register/complete: | |
$ref: 'read/register/complete.yaml' | |
"/api/confirm/{code}": | |
$ref: 'read/confirm/code.yaml' | |
/api/tos: | |
$ref: 'read/tos.yaml' | |
/api/search: | |
$ref: 'read/search.yaml' | |
"/api/reset": | |
$ref: 'read/reset.yaml' | |
"/api/reset/{code}": | |
$ref: 'read/reset/code.yaml' | |
"/api/email/unsubscribe/{token}": | |
$ref: 'read/email/unsubscribe/token.yaml' | |
"/api/post/{pid}": | |
$ref: 'read/post/pid.yaml' | |
/api/flags: | |
$ref: 'read/flags.yaml' | |
"/api/flags/{flagId}": | |
$ref: 'read/flags/flagId.yaml' | |
/api/post-queue: | |
$ref: 'read/post-queue.yaml' | |
/api/ip-blacklist: | |
$ref: 'read/ip-blacklist.yaml' | |
/api/registration-queue: | |
$ref: 'read/registration-queue.yaml' | |
/api/tags: | |
$ref: 'read/tags.yaml' | |
"/api/tags/{tag}": | |
$ref: 'read/tags/tag.yaml' | |
/api/popular: | |
$ref: 'read/popular.yaml' | |
/api/top: | |
$ref: 'read/top.yaml' | |
"/api/category/{category_id}/{slug}": | |
$ref: 'read/category/category_id.yaml' | |
"/api/category/{category_id}/{slug}/{topic_index}": | |
$ref: 'read/category/category_id.yaml' | |
/api/self: | |
$ref: 'read/self.yaml' | |
/api/me: | |
$ref: 'read/me.yaml' | |
/api/me/*: | |
$ref: 'read/me.yaml' | |
"/api/uid/{uid*}": | |
$ref: 'read/uid/uid.yaml' | |
"/api/user/{userslug}": | |
$ref: 'read/user/userslug.yaml' | |
"/api/user/{userslug}/following": | |
$ref: 'read/user/userslug/following.yaml' | |
"/api/user/{userslug}/followers": | |
$ref: 'read/user/userslug/followers.yaml' | |
"/api/user/{userslug}/categories": | |
$ref: 'read/user/userslug/categories.yaml' | |
"/api/user/{userslug}/posts": | |
$ref: 'read/user/userslug/posts.yaml' | |
"/api/user/{userslug}/topics": | |
$ref: 'read/user/userslug/topics.yaml' | |
"/api/user/{userslug}/best": | |
$ref: 'read/user/userslug/best.yaml' | |
"/api/user/{userslug}/groups": | |
$ref: 'read/user/userslug/groups.yaml' | |
"/api/user/{userslug}/bookmarks": | |
$ref: 'read/user/userslug/bookmarks.yaml' | |
"/api/user/{userslug}/watched": | |
$ref: 'read/user/userslug/watched.yaml' | |
"/api/user/{userslug}/ignored": | |
$ref: 'read/user/userslug/ignored.yaml' | |
"/api/user/{userslug}/upvoted": | |
$ref: 'read/user/userslug/upvoted.yaml' | |
"/api/user/{userslug}/downvoted": | |
$ref: 'read/user/userslug/downvoted.yaml' | |
"/api/user/{userslug}/edit": | |
$ref: 'read/user/userslug/edit.yaml' | |
"/api/user/{userslug}/edit/username": | |
$ref: 'read/user/userslug/edit/username.yaml' | |
"/api/user/{userslug}/edit/email": | |
$ref: 'read/user/userslug/edit/email.yaml' | |
"/api/user/{userslug}/edit/password": | |
$ref: 'read/user/userslug/edit/password.yaml' | |
"/api/user/{userslug}/info": | |
$ref: 'read/user/userslug/info.yaml' | |
"/api/user/{userslug}/settings": | |
$ref: 'read/user/userslug/settings.yaml' | |
"/api/user/{userslug}/uploads": | |
$ref: 'read/user/userslug/uploads.yaml' | |
"/api/user/{userslug}/consent": | |
$ref: 'read/user/userslug/consent.yaml' | |
"/api/user/{userslug}/blocks": | |
$ref: 'read/user/userslug/blocks.yaml' | |
"/api/user/{userslug}/sessions": | |
$ref: 'read/user/userslug/sessions.yaml' | |
"/api/user/{userslug}/session/{uuid}": | |
$ref: 'read/user/userslug/session/uuid.yaml' | |
/api/notifications: | |
$ref: 'read/notifications.yaml' | |
"/api/user/{userslug}/chats/{roomid}": | |
$ref: 'read/user/userslug/chats/roomid.yaml' | |
"/api/chats/{roomid}": | |
$ref: 'read/chats/roomid.yaml' | |
/api/groups: | |
$ref: 'read/groups.yaml' | |
"/api/groups/{slug}": | |
$ref: 'read/groups/slug.yaml' | |
"/api/groups/{slug}/members": | |
$ref: 'read/groups/slug/members.yaml' | |
/api/outgoing: | |
$ref: 'read/outgoing.yaml' |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment