Adding API docs for app developers.

- Fixes #99.
This commit is contained in:
Dessalines 2019-05-15 09:04:05 -07:00
parent 341656f1c4
commit 296421a888
7 changed files with 734 additions and 12 deletions

View file

@ -121,7 +121,8 @@ cd lemmy
and goto http://localhost:8536 and goto http://localhost:8536
## Documentation ## Documentation
- [ActivityPub API.md](docs/API.md) - [Websocket API for App developers](docs/api.md)
- [ActivityPub API.md](docs/apub_api_outline.md)
- [Goals](docs/goals.md) - [Goals](docs/goals.md)
- [Ranking Algorithm](docs/ranking.md) - [Ranking Algorithm](docs/ranking.md)
## Support ## Support

726
docs/api.md Normal file
View file

@ -0,0 +1,726 @@
# Lemmy API
This may lag behind the actual API endpoints [here](../server/src/api).
The data types, such as `Vec<CommentView>`, are listed [here](../server/src/db).
## Websocket API
### Endpoint
`host/api/v1/ws`
### Testing with [Websocat](https://github.com/vi/websocat)
`websocat ws://127.0.0.1:8536/api/v1/ws`
A simple test command:
`{"op": "ListCategories"}`
## Rate limits
- 3 actions per 3 minutes for signups, post, and community creation.
- 30 actions per minute for everything else.
## Errors
```rust
{
op: String,
message: String,
}
```
## API
### List
`Login, Register, CreateCommunity, CreatePost, ListCommunities, ListCategories, GetPost, GetCommunity, CreateComment, EditComment, SaveComment, CreateCommentLike, GetPosts, CreatePostLike, EditPost, SavePost, EditCommunity, FollowCommunity, GetFollowedCommunities, GetUserDetails, GetReplies, GetModlog, BanFromCommunity, AddModToCommunity, CreateSite, EditSite, GetSite, AddAdmin, BanUser, Search, MarkAllAsRead`
### User / Authentication / Admin
#### Login
The `jwt` string should be stored and used anywhere `auth` is called for.
##### Request
```rust
{
op: "Login",
data: {
username_or_email: String,
password: String
}
}
```
##### Response
```rust
{
op: String,
jwt: String
}
```
#### Register
Only the first user will be able to be the admin.
##### Request
```rust
{
op: "Register",
data: {
username: String,
email: Option<String>,
password: String,
password_verify: String,
admin: bool,
spam_timeri: i64,
}
}
```
##### Response
```rust
{
op: String,
jwt: String
}
```
#### Get User Details
##### Request
```rust
{
op: "GetUserDetails",
data: {
user_id: Option<i32>,
username: Option<String>,
sort: String,
page: Option<i64>,
limit: Option<i64>,
community_id: Option<i32>,
saved_only: bool,
auth: Option<String>,
}
}
```
##### Response
```rust
{
op: String,
user: UserView,
follows: Vec<CommunityFollowerView>,
moderates: Vec<CommunityModeratorView>,
comments: Vec<CommentView>,
posts: Vec<PostView>,
}
```
#### Get Replies / Inbox
##### Request
```rust
{
op: "GetReplies",
data: {
sort: String,
page: Option<i64>,
limit: Option<i64>,
unread_only: bool,
auth: String
}
}
```
##### Response
```rust
{
op: String,
replies: Vec<ReplyView>,
}
```
#### Mark all replies as read
##### Request
```rust
{
op: "MarkAllAsRead",
data: {
auth: String
}
}
```
##### Response
```rust
{
op: String,
replies: Vec<ReplyView>,
}
```
#### Add admin
##### Request
```rust
{
op: "AddAdmin",
data: {
user_id: i32,
added: bool,
auth: String
}
}
```
##### Response
```rust
{
op: String,
admins: Vec<UserView>,
}
```
#### Ban user
##### Request
```rust
{
op: "BanUser",
data: {
user_id: i32,
ban: bool,
reason: Option<String>,
expires: Option<i64>,
auth: String
}
}
```
##### Response
```rust
{
op: String,
user: UserView,
banned: bool,
}
```
### Site
#### List Categories
##### Request
```rust
{
op: "ListCategories"
}
```
##### Response
```rust
{
op: String,
categories: Vec<Category>
}
```
#### Search
##### Request
```rust
{
op: "Search",
data: {
q: String,
type_: String,
community_id: Option<i32>,
sort: String,
page: Option<i64>,
limit: Option<i64>,
}
}
```
##### Response
```rust
{
op: String,
comments: Vec<CommentView>,
posts: Vec<PostView>,
}
```
#### Get Modlog
##### Request
```rust
{
op: "GetModlog",
data: {
mod_user_id: Option<i32>,
community_id: Option<i32>,
page: Option<i64>,
limit: Option<i64>,
}
}
```
##### Response
```rust
{
op: String,
removed_posts: Vec<ModRemovePostView>,
locked_posts: Vec<ModLockPostView>,
removed_comments: Vec<ModRemoveCommentView>,
removed_communities: Vec<ModRemoveCommunityView>,
banned_from_community: Vec<ModBanFromCommunityView>,
banned: Vec<ModBanView>,
added_to_community: Vec<ModAddCommunityView>,
added: Vec<ModAddView>,
}
```
#### Create Site
##### Request
```rust
{
op: "CreateSite",
data: {
name: String,
description: Option<String>,
auth: String
}
}
```
##### Response
```rust
{
op: String,
site: SiteView,
}
```
#### Edit Site
##### Request
```rust
{
op: "EditSite",
data: {
name: String,
description: Option<String>,
auth: String
}
}
```
##### Response
```rust
{
op: String,
site: SiteView,
}
```
#### Get Site
##### Request
```rust
{
op: "GetSite"
}
```
##### Response
```rust
{
op: String,
site: Option<SiteView>,
admins: Vec<UserView>,
banned: Vec<UserView>,
}
```
### Community
#### Get Community
##### Request
```rust
{
op: "GetCommunity",
data: {
id: Option<i32>,
name: Option<String>,
auth: Option<String>
}
}
```
##### Response
```rust
{
op: String,
community: CommunityView,
moderators: Vec<CommunityModeratorView>,
admins: Vec<UserView>,
}
```
#### Create Community
##### Request
```rust
{
op: "CreateCommunity",
data: {
name: String,
title: String,
description: Option<String>,
category_id: i32 ,
auth: String
}
}
```
##### Response
```rust
{
op: String,
community: CommunityView
}
```
#### List Communities
##### Request
```rust
{
op: "ListCommunities",
data: {
sort: String,
page: Option<i64>,
limit: Option<i64>,
auth: Option<String>
}
}
```
##### Response
```rust
{
op: String,
communities: Vec<CommunityView>
}
```
#### Ban from Community
##### Request
```rust
{
op: "BanFromCommunity",
data: {
community_id: i32,
user_id: i32,
ban: bool,
reason: Option<String>,
expires: Option<i64>,
auth: String
}
}
```
##### Response
```rust
{
op: String,
user: UserView,
banned: bool,
}
```
#### Add Mod to Community
##### Request
```rust
{
op: "AddModToCommunity",
data: {
community_id: i32,
user_id: i32,
added: bool,
auth: String
}
}
```
##### Response
```rust
{
op: String,
moderators: Vec<CommunityModeratorView>,
}
```
#### Edit Community
Mods and admins can remove and lock a community, creators can delete it.
##### Request
```rust
{
op: "EditCommunity",
data: {
edit_id: i32,
name: String,
title: String,
description: Option<String>,
category_id: i32,
removed: Option<bool>,
deleted: Option<bool>,
reason: Option<String>,
expires: Option<i64>,
auth: String
}
}
```
##### Response
```rust
{
op: String,
community: CommunityView
}
```
#### Follow Community
##### Request
```rust
{
op: "FollowCommunity",
data: {
community_id: i32,
follow: bool,
auth: String
}
}
```
##### Response
```rust
{
op: String,
community: CommunityView
}
```
#### Get Followed Communities
##### Request
```rust
{
op: "GetFollowedCommunities",
data: {
auth: String
}
}
```
##### Response
```rust
{
op: String,
communities: Vec<CommunityFollowerView>
}
```
### Post
#### Create Post
##### Request
```rust
{
op: "CreatePost",
data: {
name: String,
url: Option<String>,
body: Option<String>,
community_id: i32,
auth: String
}
}
```
##### Response
```rust
{
op: String,
post: PostView
}
```
#### Get Post
##### Request
```rust
{
op: "GetPost",
data: {
id: i32,
auth: Option<String>
}
}
```
##### Response
```rust
{
op: String,
post: PostView,
comments: Vec<CommentView>,
community: CommunityView,
moderators: Vec<CommunityModeratorView>,
admins: Vec<UserView>,
}
```
#### Get Posts
##### Request
```rust
{
op: "GetPosts",
data: {
type_: String,
sort: String,
page: Option<i64>,
limit: Option<i64>,
community_id: Option<i32>,
auth: Option<String>
}
}
```
##### Response
```rust
{
op: String,
posts: Vec<PostView>,
}
```
#### Create Post Like
##### Request
```rust
{
op: "CreatePostLike",
data: {
post_id: i32,
score: i16,
auth: String
}
}
```
##### Response
```rust
{
op: String,
post: PostView
}
```
#### Edit Post
Mods and admins can remove and lock a post, creators can delete it.
##### Request
```rust
{
op: "EditPost",
data: {
edit_id: i32,
creator_id: i32,
community_id: i32,
name: String,
url: Option<String>,
body: Option<String>,
removed: Option<bool>,
deleted: Option<bool>,
locked: Option<bool>,
reason: Option<String>,
auth: String
}
}
```
##### Response
```rust
{
op: String,
post: PostView
}
```
#### Save Post
##### Request
```rust
{
op: "SavePost",
data: {
post_id: i32,
save: bool,
auth: String
}
}
```
##### Response
```rust
{
op: String,
post: PostView
}
```
### Comment
#### Create Comment
##### Request
```rust
{
op: "CreateComment",
data: {
content: String,
parent_id: Option<i32>,
edit_id: Option<i32>,
post_id: i32,
auth: String
}
}
```
##### Response
```rust
{
op: String,
comment: CommentView
}
```
#### Edit Comment
Mods and admins can remove a comment, creators can delete it.
##### Request
```rust
{
op: "EditComment",
data: {
content: String,
parent_id: Option<i32>,
edit_id: i32,
creator_id: i32,
post_id: i32,
removed: Option<bool>,
deleted: Option<bool>,
reason: Option<String>,
read: Option<bool>,
auth: String
}
}
```
##### Response
```rust
{
op: String,
comment: CommentView
}
```
#### Save Comment
##### Request
```rust
{
op: "SaveComment",
data: {
comment_id: i32,
save: bool,
auth: String
}
}
```
##### Response
```rust
{
op: String,
comment: CommentView
}
```
#### Create Comment Like
##### Request
```rust
{
op: "CreateCommentLike",
data: {
comment_id: i32,
post_id: i32,
score: i16,
auth: String
}
}
```
##### Response
```rust
{
op: String,
comment: CommentView
}
```

View file

@ -1,4 +1,4 @@
# API # Activitypub API outline
- Start with the [reddit API](https://www.reddit.com/dev/api), and find [Activitypub vocab](https://www.w3.org/TR/activitystreams-vocabulary/) to match it. - Start with the [reddit API](https://www.reddit.com/dev/api), and find [Activitypub vocab](https://www.w3.org/TR/activitystreams-vocabulary/) to match it.

View file

@ -192,13 +192,8 @@ fn main() {
}; };
App::with_state(state) App::with_state(state)
// redirect to websocket.html // .resource("/api/v1/rest", |r| r.method(http::Method::POST).f(|_| {})
// .resource("/", |r| r.method(http::Method::GET).f(|_| { .resource("/api/v1/ws", |r| r.route().f(chat_route))
// HttpResponse::Found()
// .header("LOCATION", "/static/websocket.html")
// .finish()
// }))
.resource("/service/ws", |r| r.route().f(chat_route))
// static resources // static resources
.resource("/", |r| r.route().f(index)) .resource("/", |r| r.route().f(index))
.handler( .handler(

View file

@ -1,4 +1,4 @@
let host = `${window.location.hostname}`; let host = `${window.location.hostname}`;
let port = `${window.location.port == "4444" ? '8536' : window.location.port}`; let port = `${window.location.port == "4444" ? '8536' : window.location.port}`;
let endpoint = `${host}:${port}`; let endpoint = `${host}:${port}`;
export let wsUri = `${(window.location.protocol=='https:') ? 'wss://' : 'ws://'}${endpoint}/service/ws`; export let wsUri = `${(window.location.protocol=='https:') ? 'wss://' : 'ws://'}${endpoint}/api/v1/ws`;

View file

@ -1 +1 @@
export let version: string = "v0.0.5-0-gf34ba11"; export let version: string = "v0.0.5-11-g8e22de3";

View file

@ -48,7 +48,7 @@ spec:
backend: backend:
serviceName: lemmy-ui--prod serviceName: lemmy-ui--prod
servicePort: 5000 servicePort: 5000
- path: /service/ws - path: /api/v1/ws
backend: backend:
serviceName: lemmy-server--prod serviceName: lemmy-server--prod
servicePort: 8536 servicePort: 8536