mirror of https://github.com/usememos/memos
boojack
2 years ago
committed by
GitHub
parent
4491c75135
commit
35f2d399e2
@ -1,107 +0,0 @@
|
||||
# Authentication APIs
|
||||
|
||||
## Sign In
|
||||
|
||||
```
|
||||
POST /api/v1/auth/signin
|
||||
```
|
||||
|
||||
**Request Body**
|
||||
|
||||
```json
|
||||
{
|
||||
"username": "john",
|
||||
"password": "password123"
|
||||
}
|
||||
```
|
||||
|
||||
**Response**
|
||||
|
||||
```json
|
||||
{
|
||||
"id": 123,
|
||||
"username": "john",
|
||||
"nickname": "John"
|
||||
// other user fields
|
||||
}
|
||||
```
|
||||
|
||||
**Status Codes**
|
||||
|
||||
- 200: Sign in success
|
||||
- 400: Invalid request
|
||||
- 401: Incorrect credentials
|
||||
- 403: User banned
|
||||
- 500: Internal server error
|
||||
|
||||
## SSO Sign In
|
||||
|
||||
```
|
||||
POST /api/v1/auth/signin/sso
|
||||
```
|
||||
|
||||
**Request Body**
|
||||
|
||||
```json
|
||||
{
|
||||
"identityProviderId": 123,
|
||||
"code": "abc123",
|
||||
"redirectUri": "https://example.com/callback"
|
||||
}
|
||||
```
|
||||
|
||||
**Response**
|
||||
|
||||
Same as **Sign In**
|
||||
|
||||
**Status Codes**
|
||||
|
||||
- 200: Success
|
||||
- 400: Invalid request
|
||||
- 401: Authentication failed
|
||||
- 403: User banned
|
||||
- 404: Identity provider not found
|
||||
- 500: Internal server error
|
||||
|
||||
## Sign Up
|
||||
|
||||
```
|
||||
POST /api/v1/auth/signup
|
||||
```
|
||||
|
||||
**Request Body**
|
||||
|
||||
```json
|
||||
{
|
||||
"username": "mary",
|
||||
"password": "password456"
|
||||
}
|
||||
```
|
||||
|
||||
**Response**
|
||||
|
||||
Same as **Sign In**
|
||||
|
||||
**Status Codes**
|
||||
|
||||
- 200: Sign up success
|
||||
- 400: Invalid request
|
||||
- 401: Sign up disabled
|
||||
- 500: Internal server error
|
||||
|
||||
## Sign Out
|
||||
|
||||
```
|
||||
POST /api/v1/auth/signout
|
||||
```
|
||||
|
||||
**Response**
|
||||
|
||||
```
|
||||
true
|
||||
```
|
||||
|
||||
**Status Codes**
|
||||
|
||||
- 200: Success
|
||||
- 500: Internal server error
|
||||
@ -1,44 +0,0 @@
|
||||
# Guide to Access Memos API with OpenID
|
||||
|
||||
Memos API supports using OpenID as the user identifier to access the API.
|
||||
|
||||
## What is OpenID
|
||||
|
||||
OpenID is a unique identifier assigned by Memos system to each user.
|
||||
|
||||
When a user registers or logs in via third-party OAuth through Memos system, the OpenID will be generated automatically.
|
||||
|
||||
## How to Get User's OpenID
|
||||
|
||||
You can get a user's OpenID through:
|
||||
|
||||
- User checks the personal profile page in Memos system
|
||||
- Calling Memos API to get user details
|
||||
- Retrieving from login API response after successful login
|
||||
|
||||
Example:
|
||||
|
||||
```
|
||||
// GET /api/v1/user/me
|
||||
|
||||
{
|
||||
"id": 123,
|
||||
"username": "john",
|
||||
"openId": "8613E04B4FA6603883F05A5E0A5E2517",
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
## How to Use OpenID to Access API
|
||||
|
||||
You can access the API on behalf of the user by appending `?openId=xxx` parameter to the API URL.
|
||||
|
||||
For example:
|
||||
|
||||
```
|
||||
curl 'https://demo.usememos.com/api/v1/memo?openId=8613E04B4FA6603883F05A5E0A5E2517' -H 'Content-Type: application/json' --data-raw '{"content":"Hello world!"}'
|
||||
```
|
||||
|
||||
The above request will create a Memo under the user with OpenID `8613E04B4FA6603883F05A5E0A5E2517`.
|
||||
|
||||
OpenID can be used in any API that requires user identity.
|
||||
@ -1,67 +0,0 @@
|
||||
# Memo Relation APIs
|
||||
|
||||
## Create Memo Relation
|
||||
|
||||
```
|
||||
POST /api/v1/memo/:memoId/relation
|
||||
```
|
||||
|
||||
**Request Body**
|
||||
|
||||
```json
|
||||
{
|
||||
"relatedMemoId": 456,
|
||||
"type": "REFERENCE"
|
||||
}
|
||||
```
|
||||
|
||||
**Response**
|
||||
|
||||
```json
|
||||
{
|
||||
"memoId": 123,
|
||||
"relatedMemoId": 456,
|
||||
"type": "REFERENCE"
|
||||
}
|
||||
```
|
||||
|
||||
**Status Codes**
|
||||
|
||||
- 200: OK
|
||||
- 400: Invalid request
|
||||
- 500: Internal server error
|
||||
|
||||
## Get Memo Relations
|
||||
|
||||
```
|
||||
GET /api/v1/memo/:memoId/relation
|
||||
```
|
||||
|
||||
**Response**
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"memoId": 123,
|
||||
"relatedMemoId": 456,
|
||||
"type": "REFERENCE"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
**Status Codes**
|
||||
|
||||
- 200: OK
|
||||
- 500: Internal server error
|
||||
|
||||
## Delete Memo Relation
|
||||
|
||||
```
|
||||
DELETE /api/v1/memo/:memoId/relation/:relatedMemoId/type/:relationType
|
||||
```
|
||||
|
||||
**Status Codes**
|
||||
|
||||
- 200: Deleted
|
||||
- 400: Invalid request
|
||||
- 500: Internal server error
|
||||
@ -1,65 +0,0 @@
|
||||
# Memo Resource APIs
|
||||
|
||||
## Bind Resource to Memo
|
||||
|
||||
```
|
||||
POST /api/v1/memo/:memoId/resource
|
||||
```
|
||||
|
||||
**Request Body**
|
||||
|
||||
```json
|
||||
{
|
||||
"resourceId": 123
|
||||
}
|
||||
```
|
||||
|
||||
**Response**
|
||||
|
||||
```
|
||||
true
|
||||
```
|
||||
|
||||
**Status Codes**
|
||||
|
||||
- 200: OK
|
||||
- 400: Invalid request
|
||||
- 401: Unauthorized
|
||||
- 404: Memo/Resource not found
|
||||
- 500: Internal server error
|
||||
|
||||
## Get Memo Resources
|
||||
|
||||
```
|
||||
GET /api/v1/memo/:memoId/resource
|
||||
```
|
||||
|
||||
**Response**
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": 123,
|
||||
"filename": "example.png"
|
||||
// other resource fields
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
**Status Codes**
|
||||
|
||||
- 200: OK
|
||||
- 500: Internal server error
|
||||
|
||||
## Unbind Resource from Memo
|
||||
|
||||
```
|
||||
DELETE /api/v1/memo/:memoId/resource/:resourceId
|
||||
```
|
||||
|
||||
**Status Codes**
|
||||
|
||||
- 200: OK
|
||||
- 401: Unauthorized
|
||||
- 404: Memo/Resource not found
|
||||
- 500: Internal server error
|
||||
@ -1,136 +0,0 @@
|
||||
# Memo APIs
|
||||
|
||||
## Create Memo
|
||||
|
||||
```
|
||||
POST /api/v1/memo
|
||||
```
|
||||
|
||||
**Request Body**
|
||||
|
||||
```json
|
||||
{
|
||||
"content": "Memo content",
|
||||
"visibility": "PUBLIC",
|
||||
"resourceIdList": [123, 456],
|
||||
"relationList": [{ "relatedMemoId": 789, "type": "REFERENCE" }]
|
||||
}
|
||||
```
|
||||
|
||||
**Response**
|
||||
|
||||
```json
|
||||
{
|
||||
"id": 1234,
|
||||
"content": "Memo content",
|
||||
"visibility": "PUBLIC"
|
||||
// other fields
|
||||
}
|
||||
```
|
||||
|
||||
**Status Codes**
|
||||
|
||||
- 200: Created
|
||||
- 400: Invalid request
|
||||
- 401: Unauthorized
|
||||
- 403: Forbidden to create public memo
|
||||
- 500: Internal server error
|
||||
|
||||
## Get Memo List
|
||||
|
||||
```
|
||||
GET /api/v1/memo
|
||||
```
|
||||
|
||||
**Parameters**
|
||||
|
||||
- `creatorId` (optional): Filter by creator ID
|
||||
- `visibility` (optional): Filter visibility, `PUBLIC`, `PROTECTED` or `PRIVATE`
|
||||
- `rowStatus` (optional): Filter Status, `ARCHIVE`, `NORMAL`, Default `NORMAL`
|
||||
- `pinned` (optional): Filter pinned memo, `true` or `false`
|
||||
- `tag` (optional): Filter memo with tag
|
||||
- `content` (optional): Search in content
|
||||
- `limit` (optional): Limit number of results
|
||||
- `offset` (optional): Offset of first result
|
||||
|
||||
**Response**
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": 1234,
|
||||
"content": "Memo 1"
|
||||
// other fields
|
||||
},
|
||||
{
|
||||
"id": 5678,
|
||||
"content": "Memo 2"
|
||||
// other fields
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
## Get Memo By ID
|
||||
|
||||
```
|
||||
GET /api/v1/memo/:memoId
|
||||
```
|
||||
|
||||
**Response**
|
||||
|
||||
```json
|
||||
{
|
||||
"id": 1234,
|
||||
"content": "Memo content"
|
||||
// other fields
|
||||
}
|
||||
```
|
||||
|
||||
**Status Codes**
|
||||
|
||||
- 200: Success
|
||||
- 403: Forbidden for private memo
|
||||
- 404: Not found
|
||||
- 500: Internal server error
|
||||
|
||||
## Update Memo
|
||||
|
||||
```
|
||||
PATCH /api/v1/memo/:memoId
|
||||
```
|
||||
|
||||
**Request Body**
|
||||
|
||||
```json
|
||||
{
|
||||
"content": "Updated content",
|
||||
"visibility": "PRIVATE"
|
||||
}
|
||||
```
|
||||
|
||||
**Response**
|
||||
|
||||
Same as **Get Memo By ID**
|
||||
|
||||
**Status Codes**
|
||||
|
||||
- 200: Updated
|
||||
- 400: Invalid request
|
||||
- 401: Unauthorized
|
||||
- 403: Forbidden
|
||||
- 404: Not found
|
||||
- 500: Internal server error
|
||||
|
||||
## Delete Memo
|
||||
|
||||
```
|
||||
DELETE /api/v1/memo/:memoId
|
||||
```
|
||||
|
||||
**Status Codes**
|
||||
|
||||
- 200: Deleted
|
||||
- 401: Unauthorized
|
||||
- 403: Forbidden
|
||||
- 404: Not found
|
||||
- 500: Internal server error
|
||||
@ -1,130 +0,0 @@
|
||||
# Resource APIs
|
||||
|
||||
## Upload Resource
|
||||
|
||||
### Upload File
|
||||
|
||||
```
|
||||
POST /api/v1/resource/blob
|
||||
```
|
||||
|
||||
**Request Form**
|
||||
|
||||
- `file`: Upload file
|
||||
|
||||
**Response**
|
||||
|
||||
```json
|
||||
{
|
||||
"id": 123,
|
||||
"filename": "example.png"
|
||||
// other fields
|
||||
}
|
||||
```
|
||||
|
||||
**Status Codes**
|
||||
|
||||
- 200: OK
|
||||
- 400: Invalid request
|
||||
- 401: Unauthorized
|
||||
- 413: File too large
|
||||
- 500: Internal server error
|
||||
|
||||
### Create Resource
|
||||
|
||||
```
|
||||
POST /api/v1/resource
|
||||
```
|
||||
|
||||
**Request Body**
|
||||
|
||||
```json
|
||||
{
|
||||
"filename": "example.png",
|
||||
"externalLink": "https://example.com/image.png"
|
||||
}
|
||||
```
|
||||
|
||||
**Response**
|
||||
|
||||
Same as **Upload File**
|
||||
|
||||
**Status Codes**
|
||||
|
||||
- 200: OK
|
||||
- 400: Invalid request
|
||||
- 401: Unauthorized
|
||||
- 500: Internal server error
|
||||
|
||||
## Get Resource List
|
||||
|
||||
```
|
||||
GET /api/v1/resource
|
||||
```
|
||||
|
||||
**Parameters**
|
||||
|
||||
- `limit` (optional): Limit number of results
|
||||
- `offset` (optional): Offset of first result
|
||||
|
||||
**Response**
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": 123,
|
||||
"filename": "example.png"
|
||||
// other fields
|
||||
},
|
||||
{
|
||||
"id": 456,
|
||||
"filename": "doc.pdf"
|
||||
// other fields
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
**Status Codes**
|
||||
|
||||
- 200: OK
|
||||
- 401: Unauthorized
|
||||
- 500: Internal server error
|
||||
|
||||
## Update Resource
|
||||
|
||||
```
|
||||
PATCH /api/v1/resource/:resourceId
|
||||
```
|
||||
|
||||
**Request Body**
|
||||
|
||||
```json
|
||||
{
|
||||
"filename": "new_name.png"
|
||||
}
|
||||
```
|
||||
|
||||
**Response**
|
||||
|
||||
Same as **Get Resource List**
|
||||
|
||||
**Status Codes**
|
||||
|
||||
- 200: OK
|
||||
- 400: Invalid request
|
||||
- 401: Unauthorized
|
||||
- 404: Not found
|
||||
- 500: Internal server error
|
||||
|
||||
## Delete Resource
|
||||
|
||||
```
|
||||
DELETE /api/v1/resource/:resourceId
|
||||
```
|
||||
|
||||
**Status Codes**
|
||||
|
||||
- 200: Deleted
|
||||
- 401: Unauthorized
|
||||
- 404: Not found
|
||||
- 500: Internal server error
|
||||
@ -1,84 +0,0 @@
|
||||
# Tag APIs
|
||||
|
||||
## Create Tag
|
||||
|
||||
```
|
||||
POST /api/v1/tag
|
||||
```
|
||||
|
||||
**Request Body**
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "python"
|
||||
}
|
||||
```
|
||||
|
||||
**Response**
|
||||
|
||||
```
|
||||
"python"
|
||||
```
|
||||
|
||||
**Status Codes**
|
||||
|
||||
- 200: Created
|
||||
- 400: Invalid request
|
||||
- 500: Internal server error
|
||||
|
||||
## Get Tag List
|
||||
|
||||
```
|
||||
GET /api/v1/tag
|
||||
```
|
||||
|
||||
**Response**
|
||||
|
||||
```json
|
||||
["python", "golang", "javascript"]
|
||||
```
|
||||
|
||||
**Status Codes**
|
||||
|
||||
- 200: OK
|
||||
- 401: Unauthorized
|
||||
- 500: Internal server error
|
||||
|
||||
## Suggest Tags
|
||||
|
||||
```
|
||||
GET /api/v1/tag/suggestion
|
||||
```
|
||||
|
||||
**Response**
|
||||
|
||||
```json
|
||||
["django", "flask", "numpy"]
|
||||
```
|
||||
|
||||
**Status Codes**
|
||||
|
||||
- 200: OK
|
||||
- 401: Unauthorized
|
||||
- 500: Internal server error
|
||||
|
||||
## Delete Tag
|
||||
|
||||
```
|
||||
POST /api/v1/tag/delete
|
||||
```
|
||||
|
||||
**Request Body**
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "outdated_tag"
|
||||
}
|
||||
```
|
||||
|
||||
**Status Codes**
|
||||
|
||||
- 200: Deleted
|
||||
- 400: Invalid request
|
||||
- 401: Unauthorized
|
||||
- 500: Internal server error
|
||||
@ -1,164 +0,0 @@
|
||||
# User APIs
|
||||
|
||||
## Create User
|
||||
|
||||
```
|
||||
POST /api/v1/user
|
||||
```
|
||||
|
||||
**Request Body**
|
||||
|
||||
```json
|
||||
{
|
||||
"username": "john",
|
||||
"role": "USER",
|
||||
"email": "john@example.com",
|
||||
"nickname": "John",
|
||||
"password": "password123"
|
||||
}
|
||||
```
|
||||
|
||||
**Response**
|
||||
|
||||
```json
|
||||
{
|
||||
"id": 123,
|
||||
"username": "john",
|
||||
"role": "USER",
|
||||
"email": "john@example.com",
|
||||
"nickname": "John",
|
||||
"avatarUrl": "",
|
||||
"createdTs": 1596647800,
|
||||
"updatedTs": 1596647800
|
||||
}
|
||||
```
|
||||
|
||||
**Status Codes**
|
||||
|
||||
- 200: Success
|
||||
- 400: Validation error
|
||||
- 401: Unauthorized
|
||||
- 403: Forbidden to create host user
|
||||
- 500: Internal server error
|
||||
|
||||
## Get User List
|
||||
|
||||
```
|
||||
GET /api/v1/user
|
||||
```
|
||||
|
||||
**Response**
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": 123,
|
||||
"username": "john",
|
||||
"role": "USER"
|
||||
// other fields
|
||||
},
|
||||
{
|
||||
"id": 456,
|
||||
"username": "mary",
|
||||
"role": "ADMIN"
|
||||
// other fields
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
**Status Codes**
|
||||
|
||||
- 200: Success
|
||||
- 500: Internal server error
|
||||
|
||||
## Get User By ID
|
||||
|
||||
```
|
||||
GET /api/v1/user/:id
|
||||
```
|
||||
|
||||
**Response**
|
||||
|
||||
```json
|
||||
{
|
||||
"id": 123,
|
||||
"username": "john",
|
||||
"role": "USER"
|
||||
// other fields
|
||||
}
|
||||
```
|
||||
|
||||
**Status Codes**
|
||||
|
||||
- 200: Success
|
||||
- 404: Not found
|
||||
- 500: Internal server error
|
||||
|
||||
## Update User
|
||||
|
||||
```
|
||||
PATCH /api/v1/user/:id
|
||||
```
|
||||
|
||||
**Request Body**
|
||||
|
||||
```json
|
||||
{
|
||||
"username": "johnny",
|
||||
"email": "johnny@example.com",
|
||||
"nickname": "Johnny",
|
||||
"avatarUrl": "https://avatars.example.com/u=123"
|
||||
}
|
||||
```
|
||||
|
||||
**Response**
|
||||
|
||||
```json
|
||||
{
|
||||
"id": 123,
|
||||
"username": "johnny",
|
||||
"role": "USER",
|
||||
"email": "johnny@example.com",
|
||||
"nickname": "Johnny",
|
||||
"avatarUrl": "https://avatars.example.com/u=123",
|
||||
"createdTs": 1596647800,
|
||||
"updatedTs": 1596647900
|
||||
}
|
||||
```
|
||||
|
||||
**Status Codes**
|
||||
|
||||
- 200: Success
|
||||
- 400: Validation error
|
||||
- 403: Forbidden
|
||||
- 404: Not found
|
||||
- 500: Internal server error
|
||||
|
||||
## Delete User
|
||||
|
||||
```
|
||||
DELETE /api/v1/user/:id
|
||||
```
|
||||
|
||||
**Status Codes**
|
||||
|
||||
- 200: Success
|
||||
- 403: Forbidden
|
||||
- 404: Not found
|
||||
- 500: Internal server error
|
||||
|
||||
## Get Current User
|
||||
|
||||
```
|
||||
GET /api/v1/user/me
|
||||
```
|
||||
|
||||
**Response**
|
||||
|
||||
Same as **Get User By ID**
|
||||
|
||||
**Status Codes**
|
||||
|
||||
- 200: Success
|
||||
- 401: Unauthorized
|
||||
- 500: Internal server error
|
||||
Loading…
Reference in New Issue