add api section to docs
This commit is contained in:
Umputun
@@ -0,0 +1,17 @@
|
||||
---
|
||||
title: Authorization
|
||||
---
|
||||
|
||||
* `GET /auth/{provider}/login?from=http://url&site=site_id&session=1` - perform "social", anonymous or email login with one of [supported providers](#register-oauth2-providers) and redirect to `url`. Presence of `session` (any non-zero value) change the default cookie expiration and makes them session-only
|
||||
* `GET /auth/logout` - logout
|
||||
|
||||
```go
|
||||
type User struct {
|
||||
Name string `json:"name"`
|
||||
ID string `json:"id"`
|
||||
Picture string `json:"picture"`
|
||||
Admin bool `json:"admin"`
|
||||
Blocked bool `json:"block"`
|
||||
Verified bool `json:"verified"`
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,114 @@
|
||||
---
|
||||
title: Commenting
|
||||
---
|
||||
|
||||
|
||||
* `POST /api/v1/comment` - add a comment, _auth required_
|
||||
|
||||
```go
|
||||
type Comment struct {
|
||||
ID string `json:"id"` // comment ID, read only
|
||||
ParentID string `json:"pid"` // parent ID
|
||||
Text string `json:"text"` // comment text, after md processing
|
||||
Orig string `json:"orig"` // original comment text
|
||||
User User `json:"user"` // user info, read only
|
||||
Locator Locator `json:"locator"` // post locator
|
||||
Score int `json:"score"` // comment score, read only
|
||||
Vote int `json:"vote"` // vote for the current user, -1/1/0
|
||||
Controversy float64 `json:"controversy,omitempty"` // comment controversy, read only
|
||||
Timestamp time.Time `json:"time"` // time stamp, read only
|
||||
Edit *Edit `json:"edit,omitempty" bson:"edit,omitempty"` // pointer to have empty default in JSON response
|
||||
Pin bool `json:"pin"` // pinned status, read only
|
||||
Delete bool `json:"delete"` // delete status, read only
|
||||
PostTitle string `json:"title"` // post title
|
||||
}
|
||||
|
||||
type Locator struct {
|
||||
SiteID string `json:"site"` // site ID
|
||||
URL string `json:"url"` // post URL
|
||||
}
|
||||
|
||||
type Edit struct {
|
||||
Timestamp time.Time `json:"time" bson:"time"`
|
||||
Summary string `json:"summary"`
|
||||
}
|
||||
```
|
||||
|
||||
* `POST /api/v1/preview` - preview comment in HTML. Body is `Comment` to render
|
||||
* `GET /api/v1/find?site=site-id&url=post-url&sort=fld&format=tree|plain` - find all comments for given post
|
||||
|
||||
This is the primary call used by UI to show comments for the given post. It can return comments in two formats - `plain` and `tree`. In plain format result will be sorted list of `Comment`. In tree format this is going to be tree-like object with this structure:
|
||||
|
||||
```go
|
||||
type Tree struct {
|
||||
Nodes []Node `json:"comments"`
|
||||
Info store.PostInfo `json:"info,omitempty"`
|
||||
}
|
||||
|
||||
type Node struct {
|
||||
Comment store.Comment `json:"comment"`
|
||||
Replies []Node `json:"replies,omitempty"`
|
||||
}
|
||||
```
|
||||
|
||||
Sort can be `time`, `active` or `score`. Supported sort order with prefix -/+, i.e. `-time`. For `tree` mode sort will be applied to top-level comments only and all replies are always sorted by time.
|
||||
|
||||
* `PUT /api/v1/comment/{id}?site=site-id&url=post-url` - edit comment, allowed once in `EDIT_TIME` minutes since creation. Body is `EditRequest` JSON
|
||||
|
||||
```go
|
||||
type EditRequest struct {
|
||||
Text string `json:"text"` // updated text
|
||||
Summary string `json:"summary"` // optional, summary of the edit
|
||||
Delete bool `json:"delete"` // delete flag
|
||||
}{}
|
||||
```
|
||||
|
||||
* `GET /api/v1/last/{max}?site=site-id&since=ts-msec` - get up to `{max}` last comments, `since` (epoch time, milliseconds) is optional
|
||||
* `GET /api/v1/id/{id}?site=site-id` - get comment by `comment id`
|
||||
* `GET /api/v1/comments?site=site-id&user=id&limit=N` - get comment by `user id`, returns `response` object
|
||||
|
||||
```go
|
||||
type response struct {
|
||||
Comments []store.Comment `json:"comments"`
|
||||
Count int `json:"count"`
|
||||
}{}
|
||||
```
|
||||
|
||||
* `GET /api/v1/count?site=site-id&url=post-url` - get comment's count for `{url}`
|
||||
* `POST /api/v1/count?site=siteID` - get number of comments for posts from post body (list of post IDs)
|
||||
* `GET /api/v1/list?site=site-id&limit=5&skip=2` - list commented posts, returns array or `PostInfo`, limit=0 will return all posts
|
||||
|
||||
```go
|
||||
type PostInfo struct {
|
||||
URL string `json:"url"`
|
||||
Count int `json:"count"`
|
||||
ReadOnly bool `json:"read_only,omitempty"`
|
||||
FirstTS time.Time `json:"first_time,omitempty"`
|
||||
LastTS time.Time `json:"last_time,omitempty"`
|
||||
}
|
||||
```
|
||||
|
||||
* `GET /api/v1/user` - get user info, _auth required_
|
||||
* `PUT /api/v1/vote/{id}?site=site-id&url=post-url&vote=1` - vote for comment. `vote`=1 will increase score, -1 decrease, _auth required_
|
||||
* `GET /api/v1/userdata?site=site-id` - export all user data to gz stream, _auth required_
|
||||
* `POST /api/v1/deleteme?site=site-id` - request deletion of user data, _auth required_
|
||||
* `GET /api/v1/config?site=site-id` - returns configuration (parameters) for given site
|
||||
|
||||
```go
|
||||
type Config struct {
|
||||
Version string `json:"version"`
|
||||
EditDuration int `json:"edit_duration"`
|
||||
MaxCommentSize int `json:"max_comment_size"`
|
||||
Admins []string `json:"admins"`
|
||||
AdminEmail string `json:"admin_email"`
|
||||
Auth []string `json:"auth_providers"`
|
||||
LowScore int `json:"low_score"`
|
||||
CriticalScore int `json:"critical_score"`
|
||||
PositiveScore bool `json:"positive_score"`
|
||||
ReadOnlyAge int `json:"readonly_age"`
|
||||
MaxImageSize int `json:"max_image_size"`
|
||||
EmojiEnabled bool `json:"emoji_enabled"`
|
||||
}
|
||||
```
|
||||
|
||||
* `GET /api/v1/info?site=site-idd&url=post-url` - returns `PostInfo` for site and URL
|
||||
+122
-55
@@ -1,59 +1,126 @@
|
||||
[
|
||||
{
|
||||
"section": "Getting Started",
|
||||
{
|
||||
"section": "Getting Started",
|
||||
"children": [
|
||||
{
|
||||
"title": "Installation",
|
||||
"href": "/getting-started/installation/"
|
||||
},
|
||||
{
|
||||
"title": "System Requirements",
|
||||
"href": "/getting-started/system-requirements/"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"section": "Configuration",
|
||||
"children": [
|
||||
{
|
||||
"title": "Frontend",
|
||||
"href": "/configuration/frontend/"
|
||||
},
|
||||
{
|
||||
"title": "Authorization",
|
||||
"href": "/configuration/authorization/"
|
||||
},
|
||||
{
|
||||
"title": "Email",
|
||||
"href": "/configuration/email/"
|
||||
},
|
||||
{
|
||||
"title": "Notifications",
|
||||
"href": "/configuration/notifications/"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"section": "Manuals",
|
||||
"children": [
|
||||
{
|
||||
"title": "Subdomain",
|
||||
"href": "/manuals/subdomain/"
|
||||
},
|
||||
{
|
||||
"title": "Reproxy",
|
||||
"href": "/manuals/reproxy/"
|
||||
},
|
||||
{
|
||||
"title": "Nginx",
|
||||
"href": "/manuals/nginx/"
|
||||
},
|
||||
{
|
||||
"title": "Kubernetes",
|
||||
"href": "/manuals/kubernetes/"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"section": "Backup",
|
||||
"children": [
|
||||
{
|
||||
"title": "Manual",
|
||||
"href": "/backup/manual/"
|
||||
},
|
||||
{
|
||||
"title": "Migration",
|
||||
"href": "/backup/migration/"
|
||||
},
|
||||
{
|
||||
"title": "Restore",
|
||||
"href": "/backup/restore/"
|
||||
},
|
||||
{
|
||||
"title": "Site URL migration",
|
||||
"href": "/backup/url-migration/"
|
||||
},
|
||||
{
|
||||
"title": "Automatic",
|
||||
"href": "/backup/automatic/"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"section": "API",
|
||||
"children": [
|
||||
{
|
||||
"title": "Authorization",
|
||||
"href": "/api/authorization/"
|
||||
},
|
||||
{
|
||||
"title": "Commenting",
|
||||
"href": "/api/commenting/"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"section": "Contributing",
|
||||
"children": [
|
||||
{
|
||||
"title": "Development",
|
||||
"href": "/contributing/development/",
|
||||
"children": [
|
||||
{ "title": "Installation", "href": "/getting-started/installation/" },
|
||||
{
|
||||
"title": "System Requirements",
|
||||
"href": "/getting-started/system-requirements/"
|
||||
}
|
||||
{
|
||||
"title": "Backend",
|
||||
"href": "/contributing/development/backend/"
|
||||
},
|
||||
{
|
||||
"title": "Frontend",
|
||||
"href": "/contributing/development/frontend/"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"section": "Configuration",
|
||||
"children": [
|
||||
{ "title": "Frontend", "href": "/configuration/frontend/" },
|
||||
{ "title": "Authorization", "href": "/configuration/authorization/" },
|
||||
{ "title": "Email", "href": "/configuration/email/" },
|
||||
{ "title": "Notifications", "href": "/configuration/notifications/" }
|
||||
]
|
||||
},
|
||||
{
|
||||
"section": "Manuals",
|
||||
"children": [
|
||||
{ "title": "Subdomain", "href": "/manuals/subdomain/" },
|
||||
{ "title": "Reproxy", "href": "/manuals/reproxy/" },
|
||||
{ "title": "Nginx", "href": "/manuals/nginx/" },
|
||||
{ "title": "Kubernetes", "href": "/manuals/kubernetes/" }
|
||||
]
|
||||
},
|
||||
{
|
||||
"section": "Backup",
|
||||
"children": [
|
||||
{ "title": "Manual", "href": "/backup/manual/" },
|
||||
{ "title": "Migration", "href": "/backup/migration/" },
|
||||
{ "title": "Restore", "href": "/backup/restore/" },
|
||||
{ "title": "Site URL migration", "href": "/backup/url-migration/" },
|
||||
{ "title": "Automatic", "href": "/backup/automatic/" }
|
||||
]
|
||||
},
|
||||
{
|
||||
"section": "Contrubuting",
|
||||
"children": [
|
||||
{
|
||||
"title": "Development",
|
||||
"href": "/contributing/development/",
|
||||
"children": [
|
||||
{ "title": "Backend", "href": "/contributing/development/backend/" },
|
||||
{ "title": "Frontend", "href": "/contributing/development/frontend/" }
|
||||
]
|
||||
},
|
||||
{ "title": "Translations", "href": "/contributing/translations/" },
|
||||
{ "title": "API", "href": "/contributing/api/" },
|
||||
{
|
||||
"title": "Technical Details",
|
||||
"href": "/contributing/technical-details/"
|
||||
}
|
||||
]
|
||||
}
|
||||
},
|
||||
{
|
||||
"title": "Translations",
|
||||
"href": "/contributing/translations/"
|
||||
},
|
||||
{
|
||||
"title": "API",
|
||||
"href": "/contributing/api/"
|
||||
},
|
||||
{
|
||||
"title": "Technical Details",
|
||||
"href": "/contributing/technical-details/"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
|
||||
Reference in New Issue
Block a user