You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
320 lines
12 KiB
YAML
320 lines
12 KiB
YAML
openapi: 3.0.0
|
|
info:
|
|
title: NodeBB Read API
|
|
version: 3.0.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 do not 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
|
|
|
|
By default, the API will attempt to find a valid session in the browser's cookies. 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.
|
|
|
|
Most data transfer utilities like cURL will allow you to construct something like a cookie, to be sent alongside the request, to function much like a browser cookie. This should work with the API.
|
|
|
|
### Bearer Authentication
|
|
|
|
Both the Read API and Write API offer bearer authentication, as administered through the administration panel.
|
|
|
|
* Up until v1.14.3, 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.
|
|
* From NodeBB v1.15.0 onwards, the Write API is available in core, and bearer authentication is available out-of-the-box
|
|
|
|
In both cases, a bearer token is issued in the NodeBB admin panel in order to grant access to the API.
|
|
|
|
There are two types of tokens:
|
|
* A *user token* is associated with a specific uid, and all calls made are made in the name of that user
|
|
* A *master token* is not associated with any specific uid, though a `_uid` parameter is required in the request, and then all calls are made in the name of *that* user.
|
|
This is the only difference between the two tokens. A master token with `_uid` set to a non-administrator will not allow you to make administrative calls.
|
|
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/dashboard/logins:
|
|
$ref: 'read/admin/dashboard/logins.yaml'
|
|
/api/admin/dashboard/users:
|
|
$ref: 'read/admin/dashboard/users.yaml'
|
|
/api/admin/dashboard/topics:
|
|
$ref: 'read/admin/dashboard/topics.yaml'
|
|
/api/admin/dashboard/searches:
|
|
$ref: 'read/admin/dashboard/searches.yaml'
|
|
"/api/admin/settings/{term}":
|
|
$ref: 'read/admin/settings/term.yaml'
|
|
/api/admin/settings/navigation:
|
|
$ref: 'read/admin/settings/navigation.yaml'
|
|
/api/admin/settings/api:
|
|
$ref: 'read/admin/settings/api.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/settings/advanced:
|
|
$ref: 'read/admin/settings/advanced.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/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/post-queue/{id}":
|
|
$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}/controversial":
|
|
$ref: 'read/user/userslug/controversial.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' |