diff options
author | Dessalines <tyhou13@gmx.com> | 2019-05-15 09:04:05 -0700 |
---|---|---|
committer | Dessalines <tyhou13@gmx.com> | 2019-05-15 09:04:05 -0700 |
commit | 5e1fcd318a7337be1add92e27d4c4fec0600aec7 (patch) | |
tree | 03b84a28736f2747966d33821d29ddbc480b86ab | |
parent | 74fb8ebcc8ea756b8fffd9423e3259940125cc82 (diff) |
Adding API docs for app developers.
- Fixes #99.
-rw-r--r-- | README.md | 3 | ||||
-rw-r--r-- | docs/api.md | 726 | ||||
-rw-r--r-- | docs/apub_api_outline.md (renamed from docs/API.md) | 2 | ||||
-rw-r--r-- | server/src/main.rs | 9 | ||||
-rw-r--r-- | ui/src/env.ts | 2 | ||||
-rw-r--r-- | ui/src/version.ts | 2 | ||||
-rw-r--r-- | ui/stack.prod.yaml | 2 |
7 files changed, 734 insertions, 12 deletions
@@ -121,7 +121,8 @@ cd lemmy and goto http://localhost:8536 ## 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) - [Ranking Algorithm](docs/ranking.md) ## Support diff --git a/docs/api.md b/docs/api.md new file mode 100644 index 00000000..a3b459b5 --- /dev/null +++ b/docs/api.md @@ -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 +} +``` diff --git a/docs/API.md b/docs/apub_api_outline.md index 78cc81ab..e2776308 100644 --- a/docs/API.md +++ b/docs/apub_api_outline.md @@ -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. diff --git a/server/src/main.rs b/server/src/main.rs index fc27531b..48074316 100644 --- a/server/src/main.rs +++ b/server/src/main.rs @@ -192,13 +192,8 @@ fn main() { }; App::with_state(state) - // redirect to websocket.html - // .resource("/", |r| r.method(http::Method::GET).f(|_| { - // HttpResponse::Found() - // .header("LOCATION", "/static/websocket.html") - // .finish() - // })) - .resource("/service/ws", |r| r.route().f(chat_route)) + // .resource("/api/v1/rest", |r| r.method(http::Method::POST).f(|_| {}) + .resource("/api/v1/ws", |r| r.route().f(chat_route)) // static resources .resource("/", |r| r.route().f(index)) .handler( diff --git a/ui/src/env.ts b/ui/src/env.ts index aebbc57f..a0cdcdb0 100644 --- a/ui/src/env.ts +++ b/ui/src/env.ts @@ -1,4 +1,4 @@ let host = `${window.location.hostname}`; let port = `${window.location.port == "4444" ? '8536' : window.location.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`; diff --git a/ui/src/version.ts b/ui/src/version.ts index 1bc67c9b..4dc14542 100644 --- a/ui/src/version.ts +++ b/ui/src/version.ts @@ -1 +1 @@ -export let version: string = "v0.0.5-0-gf34ba11";
\ No newline at end of file +export let version: string = "v0.0.5-11-g8e22de3";
\ No newline at end of file diff --git a/ui/stack.prod.yaml b/ui/stack.prod.yaml index 85ac6f6b..ca4e1a7d 100644 --- a/ui/stack.prod.yaml +++ b/ui/stack.prod.yaml @@ -48,7 +48,7 @@ spec: backend: serviceName: lemmy-ui--prod servicePort: 5000 - - path: /service/ws + - path: /api/v1/ws backend: serviceName: lemmy-server--prod servicePort: 8536 |