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.
464 lines
12 KiB
YAML
464 lines
12 KiB
YAML
openapi: 3.0.0
|
|
info:
|
|
description: 'Standard, out-of-the-box read & write API for NodeBB v2.0+'
|
|
version: 31-03-2020
|
|
title: Read/Write API
|
|
contact:
|
|
email: support@nodebb.org
|
|
license:
|
|
name: MIT
|
|
url: 'https://opensource.org/licenses/MIT'
|
|
tags:
|
|
- name: users
|
|
description: 'Account related calls (create, modify, delete, etc.)'
|
|
paths:
|
|
/:
|
|
post:
|
|
tags:
|
|
- users
|
|
summary: creates a user account
|
|
description: This operation creates a new user account
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
username:
|
|
type: string
|
|
description: 'If the username is taken, a number will be appended'
|
|
password:
|
|
type: string
|
|
email:
|
|
type: string
|
|
required:
|
|
- username
|
|
example:
|
|
username: Dragon Fruit
|
|
password: s3cre7password
|
|
email: dragonfruit@example.org
|
|
responses:
|
|
'200':
|
|
description: user successfully created
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
status:
|
|
$ref: '#/components/schemas/Status'
|
|
response:
|
|
$ref: '#/components/schemas/UserObj'
|
|
'400':
|
|
$ref: '#/components/responses/400'
|
|
'401':
|
|
$ref: '#/components/responses/401'
|
|
'403':
|
|
$ref: '#/components/responses/403'
|
|
'426':
|
|
$ref: '#/components/responses/426'
|
|
'500':
|
|
$ref: '#/components/responses/500'
|
|
delete:
|
|
tags:
|
|
- users
|
|
summary: deletes one or more users
|
|
description: This operation deletes one or many user accounts, including their contributions (posts, topics, etc.)
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
uids:
|
|
type: array
|
|
description: A collection of uids
|
|
items:
|
|
type: number
|
|
example:
|
|
uids:
|
|
- 1
|
|
- 2
|
|
- 3
|
|
responses:
|
|
'200':
|
|
description: user account(s) deleted
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
status:
|
|
$ref: '#/components/schemas/Status'
|
|
response:
|
|
type: object
|
|
'/{uid}':
|
|
put:
|
|
tags:
|
|
- users
|
|
summary: updates a user account
|
|
parameters:
|
|
- in: path
|
|
name: uid
|
|
schema:
|
|
type: integer
|
|
required: true
|
|
description: uid of the user to update
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/UserRequest'
|
|
responses:
|
|
'200':
|
|
description: user profile updated
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
status:
|
|
$ref: '#/components/schemas/Status'
|
|
response:
|
|
$ref: '#/components/schemas/UserObj'
|
|
'401':
|
|
$ref: '#/components/responses/401'
|
|
'403':
|
|
$ref: '#/components/responses/403'
|
|
'426':
|
|
$ref: '#/components/responses/426'
|
|
'500':
|
|
$ref: '#/components/responses/500'
|
|
delete:
|
|
tags:
|
|
- users
|
|
summary: delete a single user account
|
|
parameters:
|
|
- in: path
|
|
name: uid
|
|
schema:
|
|
type: integer
|
|
required: true
|
|
description: uid of the user to delete
|
|
responses:
|
|
'200':
|
|
description: user account deleted
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
status:
|
|
$ref: '#/components/schemas/Status'
|
|
response:
|
|
type: object
|
|
'/{uid}/password':
|
|
put:
|
|
tags:
|
|
- users
|
|
summary: changes a user's password
|
|
parameters:
|
|
- in: path
|
|
name: uid
|
|
schema:
|
|
type: integer
|
|
required: true
|
|
description: uid of the user to update
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
currentPassword:
|
|
type: string
|
|
description: test
|
|
example: oldp455word
|
|
newPassword:
|
|
type: string
|
|
example: s3cre7password
|
|
required:
|
|
- newPassword
|
|
responses:
|
|
'200':
|
|
description: user profile updated
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
status:
|
|
$ref: '#/components/schemas/Status'
|
|
response:
|
|
type: object
|
|
'/{uid}/follow':
|
|
post:
|
|
tags:
|
|
- users
|
|
summary: follows a user
|
|
parameters:
|
|
- in: path
|
|
name: uid
|
|
schema:
|
|
type: integer
|
|
required: true
|
|
description: uid of the user to follow
|
|
responses:
|
|
'200':
|
|
description: successfully followed user
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
status:
|
|
$ref: '#/components/schemas/Status'
|
|
response:
|
|
type: object
|
|
delete:
|
|
tags:
|
|
- users
|
|
summary: unfollows a user
|
|
parameters:
|
|
- in: path
|
|
name: uid
|
|
schema:
|
|
type: integer
|
|
required: true
|
|
description: uid of the user to unfollow
|
|
responses:
|
|
'200':
|
|
description: successfully unfollowed user
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
status:
|
|
$ref: '#/components/schemas/Status'
|
|
response:
|
|
type: object
|
|
components:
|
|
schemas:
|
|
Status:
|
|
type: object
|
|
properties:
|
|
code:
|
|
allOf:
|
|
- title: Success
|
|
type: string
|
|
example: ok
|
|
- title: Error
|
|
type: string
|
|
example: error
|
|
message:
|
|
type: string
|
|
example: OK
|
|
Error:
|
|
type: object
|
|
properties:
|
|
status:
|
|
type: object
|
|
properties:
|
|
code:
|
|
type: string
|
|
message:
|
|
type: string
|
|
response:
|
|
type: object
|
|
UserObj:
|
|
properties:
|
|
uid:
|
|
type: number
|
|
example: 1
|
|
username:
|
|
type: string
|
|
example: Dragon Fruit
|
|
userslug:
|
|
type: string
|
|
example: dragon-fruit
|
|
email:
|
|
type: string
|
|
example: dragonfruit@example.org
|
|
'email:confirmed':
|
|
type: number
|
|
example: 1
|
|
joindate:
|
|
type: number
|
|
example: 1585337827953
|
|
lastonline:
|
|
type: number
|
|
example: 1585337827953
|
|
picture:
|
|
type: string
|
|
example: 'https://images.unsplash.com/photo-1560070094-e1f2ddec4337?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=256&h=256&q=80'
|
|
fullname:
|
|
type: string
|
|
example: Mr. Dragon Fruit Jr.
|
|
location:
|
|
type: string
|
|
example: 'Toronto, Canada'
|
|
birthday:
|
|
type: string
|
|
description: A birthdate given in an ISO format parseable by the Date object
|
|
example: 03/27/2020
|
|
website:
|
|
type: string
|
|
example: 'https://example.org'
|
|
aboutme:
|
|
type: string
|
|
example: |
|
|
This is a paragraph all about how my life got twist-turned upside-down
|
|
and I'd like to take a minute and sit right here,
|
|
to tell you all about how I because the administrator of NodeBB
|
|
signature:
|
|
type: string
|
|
example: |
|
|
This is an example signature
|
|
It can span multiple lines.
|
|
uploadedpicture:
|
|
type: string
|
|
example: /assets/profile/1-profileimg.png
|
|
description: 'In almost all cases, defer to "picture" instead. Use this if you need to specifically reference the picture uploaded to the forum.'
|
|
profileviews:
|
|
type: number
|
|
example: 1000
|
|
reputation:
|
|
type: number
|
|
example: 100
|
|
postcount:
|
|
type: number
|
|
example: 1000
|
|
topiccount:
|
|
type: number
|
|
example: 50
|
|
lastposttime:
|
|
type: number
|
|
example: 1585337827953
|
|
banned:
|
|
type: number
|
|
example: 0
|
|
'banned:expire':
|
|
type: number
|
|
example: 1585337827953
|
|
status:
|
|
type: string
|
|
example: online
|
|
flags:
|
|
type: number
|
|
example: 0
|
|
followercount:
|
|
type: number
|
|
example: 2
|
|
followingcount:
|
|
type: number
|
|
example: 5
|
|
'cover:url':
|
|
type: string
|
|
example: /assets/profile/1-cover.png
|
|
'cover:position':
|
|
type: string
|
|
example: 50.0301% 19.2464%
|
|
groupTitle:
|
|
type: string
|
|
example: '["administrators","Staff"]'
|
|
groupTitleArray:
|
|
type: array
|
|
example:
|
|
- administrators
|
|
- Staff
|
|
'icon:text':
|
|
type: string
|
|
example: D
|
|
'icon:bgColor':
|
|
type: string
|
|
example: '#9c27b0'
|
|
joindateISO:
|
|
type: string
|
|
example: '2020-03-27T20:30:36.590Z'
|
|
lastonlineISO:
|
|
type: string
|
|
example: '2020-03-27T20:30:36.590Z'
|
|
banned_until:
|
|
type: number
|
|
example: 0
|
|
banned_until_readable:
|
|
type: string
|
|
example: Not Banned
|
|
UserRequest:
|
|
properties:
|
|
username:
|
|
type: string
|
|
example: Dragon Fruit
|
|
email:
|
|
type: string
|
|
example: dragonfruit@example.org
|
|
fullname:
|
|
type: string
|
|
example: Mr. Dragon Fruit Jr.
|
|
website:
|
|
type: string
|
|
example: 'https://example.org'
|
|
location:
|
|
type: string
|
|
example: 'Toronto, Canada'
|
|
groupTitle:
|
|
type: string
|
|
example: '["administrators","Staff"]'
|
|
birthday:
|
|
type: string
|
|
description: A birthdate given in an ISO format parseable by the Date object
|
|
example: 03/27/2020
|
|
signature:
|
|
type: string
|
|
example: |
|
|
This is an example signature
|
|
It can span multiple lines.
|
|
aboutme:
|
|
type: string
|
|
example: |
|
|
This is a paragraph all about how my life got twist-turned upside-down
|
|
and I'd like to take a minute and sit right here,
|
|
to tell you all about how I because the administrator of NodeBB
|
|
responses:
|
|
'400':
|
|
description: Bad Request
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
'401':
|
|
description: Not Authorized
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
'403':
|
|
description: Forbidden
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
'404':
|
|
description: Not Found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
'426':
|
|
description: Upgrade Required
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
'500':
|
|
description: Internal Server Error
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|