API.md

API Documentation

ROOT

/necore

Slogan

• request

GET /slogan

• response

{
    "slogan": "string"
}

Auth

User group includes ["admin", "news_admin", "server_admin", "document_admin"]. If empty, the user doesn"t have permission to manage corresponding resources.

Auth uses JWT Token.

Status

GET /auth/status

• response

{
    "status": "alive" | "dead",
}

Login

• request

POST /auth/login

{
    "username": "string",
    "password": "string"
}

• response

{
    "token": "string",
    "user": {
        "username": "string",
        "group": "string[]",
        "tags": [{
            "text": "string",
            "color": "string",
            "tagColor": "string",
        }, ...]
    },
    "error": "string" // if error
}

Register

• auth

Only Admin can create accounts.

• request

POST /auth/register

{
    "username": "string",
    "password": "string",
}

• response

{
    "error": "string" // if error
}

User Avatar

• auth

Any user

• request

GET /auth/avatar/:id

• response

{
    "avatar": "string"
}

User Info

• auth

Current user or Admin

• request

GET /auth/user/:id

• response

{
    "user": {
        "username": "string",
        "group": "string[]",
        "tags": [{
            "text": "string",
            "color": "string",
            "tagColor": "string",
        }, ...]
    },
}

All User Info

• auth

Only Admin can see all users.

• request

GET /auth/userlist

• response

{
    "users": [
        {
            "username": "string",
            "group": "string[]",
            "tags": [{
                "text": "string",
                "color": "string",
                "tagColor": "string",
            }, ...]
        },
    ],
}

Delete User

• auth

Only Admin can delete accounts.

• request

DELETE /auth/user/:id

• response

{
    "error": "string" // if error
}

Update Password

• auth

User can update their own password. Admin can change password of others.

• request

POST /auth/password

{
    "id": "string",
    "self_password": "string",
    "new_password": "string",
}

Update Avatar

• auth

User can update their own avatar.

• request

POST /auth/avatar

{
    "username": "string",
    "avatar": "string"
}

• response

{
    "error": "string" // if error
}

• response

{
    "error": "string" // if error
}

Update User Info

• auth

Admin can change group and tag of others.

• request

PATCH /auth/user

{
    "username": "string",
    "group": "string[]",
    "tags": [{
        "text": "string",
        "color": "string",
        "tagColor": "string",
    }, ...]
}

• response

{
    "error": "string" // if error
}

Server

Get Server List

• request

GET /server

• response

{
    "servers":
    [
        {
            
            "name": "string",
            "icon": "string",
            "description": "string",
            "onlineMapUrl": "string",
            "realtime": "boolean", 
            "serverUrl": "string",
        },
        ...
    ]
}

Get Server Status

• request

POST server/status

{
    "serverUrl": "string",
}

• response

{
    "online": "boolean",
    // If online is true, the following fields should be available
    "icon": "string",
    "playerCount": "number",
    "capacity": "number",
    "latency": "number",
    "version": "string",
}

Create Server

• request

GET /server/create

• response

{
    "id": "string"
}

Update Server

• request

PATCH /server

{
    "id": "string",
    "name": "string",
    "icon": "string",
    "description": "string",
    "realtime": "boolean",
    "onlineMapUrl": "string",
    "serverUrl": "string",
}

• response

{
    "error": "string" // if error
}

Delete Server

• auth

Admin or server_admin

• request

DELETE /server/:id

• response

{
    "error": "string" // if error
}

News

Get News Total

• request

GET /news/total/:target

target: "information" | "magazine" | "notice" | "activity",

• response

{
    "total": "int"
}

Get News List

• request

POST /news/list

{
    "target": "information" | "magazine" | "notice" | "activity",
    "page": "int",
    "page_size": "int",
    "pin": "boolean", // whether to show pinned news
}

• response

{
    "list": [
        {
            "id": "string",
            "pin": "boolean",
            "title": "string",
            "brief": "string",
            "date": "string",
            "image": "string",
        },
        ...
    ]
}

Get News Detail

• request

GET /news/detail/:id

• response

{
    "entity": {
        "pin": "boolean",
        "title": "string",
        "brief": "string",
        "date": "string",
        "endDate": "string", // Optional
        "image": "string",
    },
    "content": [
        {
            "type": "markdown" | "pdf_file",
            "content": "string", // markdown content or file url
        },
        ...
    ],
    "author": "string:username",
    "category": "information" | "magazine" | "notice" | "activity",
}

Update News

• request

PATCH /news/:id

{
    "entity": {
        "pin": "boolean",
        "title": "string",
        "brief": "string",
        "date": "string",
        "endDate": "string", // Optional
        "image": "string",
    },
    "content": [
        {
            "type": "markdown" | "pdf_file",
            "content": "string", // markdown content or file url
        },
        ...
    ],
    "category": "information" | "magazine" | "notice" | "activity",
}

• response

{
  "error": "string" // if error
}

Upload file resource

• request

POST /news/upload/:id

with multipart/form-data file upload

• response

{
    "url": "string" // will be combined with backend url base, should be undefined if error
}

Remove file resource

• request

DELETE /news/upload/:id

{
    "url": "string" // backend url base should be removed
}

• response

{
    "error": "string" // if error
}

Create News

• request

POST /news/create

创建一个空的新闻，返回其ID，编辑通过update来实现

• response

{
    "id": "string",
    "error": "string" // if error
}

Delete News

• request

DELETE /news/:id

• response

{
    "error": "string" // if error
}

Document

Delete Document Node

• request

DELETE /documents/node/:id

• response

{
    "error": "string" // if error
}

Rebind Document Node

• request

POST /documents/node/:id

{
    "parentId": "string", // Should be "root" if there is no parent
}

• response

{
    "error": "string" // if error
}

Update Document Node

• request

PUT /documents/node/:id

{
    "private": "boolean",
    "content": [{
        "type": "markdown" | "pdf_file",
        "content": "string", // markdown content or file url
    }, ...],
}

• response

{
    "error": "string" // if error
}

Rename Document Node

• request

PATCH /documents/node/:id

{
    "name": "string"
}

• response

{
    "error": "string" // if error
}

Create Document Node

• request

POST /documents/node

{
    "parentId": "string", // Should be "root" if there is no parent
    "isFolder": "boolean",
    "private": "boolean",

    "name": "string"
}

• response

{
    "id": "string", // if not error
    "error": "string" // if error
}

Get Document Tree Layer (include private document)

GET /documents/layer/private/:parentId // parentId should be "root" if there is no parent

• response

{
    "children": [
        {
            "parentId": "string", // Should be "root" if there is no parent
            "id": "string",
            "isFolder": "boolean",
            "private": "boolean",

            "name": "string"
        }
    ]
}

Get Document Detail

• request

GET /documents/:id

• response

{
    "parentId": "string", // Should be "root" if there is no parent
    "id": "string",
    "isFolder": "boolean",
    "private": "boolean",
    "name": "string",
    "contributors": "string[]", // invalid if isFolder is true
    "content": [{
        "type": "markdown" | "pdf_file",
        "content": "string", // markdown content or file url
    }, ...], // invalid if isFolder is true
    "updateTime": "string" // format: yyyy-MM-dd, invalid if isFolder is true
}

Get Document Detail Private

• request

GET /documents/private/:id

• response

{
    "parentId": "string", // Should be "root" if there is no parent
    "id": "string",
    "isFolder": "boolean",
    "private": "boolean",
    "name": "string",
    "contributors": "string[]", // invalid if isFolder is true
    "content": [{
        "type": "markdown" | "pdf_file",
        "content": "string", // markdown content or file url
    }, ...], // invalid if isFolder is true
    "updateTime": "string" // format: yyyy-MM-dd, invalid if isFolder is true
}

Get Document Tree Layer

GET /documents/layer/:parentId // parentId should be "root" if there is no parent

• response

{
    "children": [
        {
            "parentId": "string", // Should be "root" if there is no parent
            "id": "string",
            "isFolder": "boolean",
            "private": "boolean",

            "name": "string",
        }
    ]
}

Upload file resource

• request

POST /documents/upload/:id

with multipart/form-data file upload

• response

{
    "url": "string" // will be combined with backend url base, should be undefined if error
}

Remove file resource

• request

DELETE /documents/upload/:id

{
    "url": "string" // backend url base should be removed
}

• response

{
    "error": "string" // if error
}