mirrors/lemmy
1
0
Fork 0
mirror of https://github.com/LemmyNet/lemmy.git synced 2024-06-02 21:49:22 +00:00
Code Issues Projects Releases Wiki Activity
lemmy/docs/api.md
Dessalines 70628d89c0 Squashed commit of the following: 
commit 309d3ec01f
Author: Dessalines <happydooby@gmail.com>
Date:   Tue Aug 13 19:49:38 2019 -0700

    Adding some docs

commit da18d30437
Author: Dessalines <happydooby@gmail.com>
Date:   Tue Aug 13 19:28:46 2019 -0700

    Adding save user settings

commit 0cd84440f4
Merge: 3246d5d c148eef
Author: Dessalines <happydooby@gmail.com>
Date:   Tue Aug 13 17:26:25 2019 -0700

    Merge branch 'dev' into nsfw

commit 3246d5d670
Author: Dessalines <happydooby@gmail.com>
Date:   Sun Aug 11 20:55:09 2019 -0700

    nsfw mostly done, except for settings page.
2019-08-13 19:52:43 -07:00

10 KiB
Raw Blame History

Lemmy API

This may lag behind the actual API endpoints here.

The data types, such as Vec<CommentView>, are listed here.

Websocket API

Endpoint

host/api/v1/ws

Testing with Websocat

websocat ws://127.0.0.1:8536/api/v1/ws -nt

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

{
  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, SaveUserSettings

Sort Types

These go wherever there is a sort field. Hot, New, TopDay, TopWeek, TopMonth, TopYear, TopAll

User / Authentication / Admin

Login

The jwt string should be stored and used anywhere auth is called for.

Request
{
  op: "Login",
  data: {
    username_or_email: String,
    password: String
  }
}
Response
{
  op: String,
  jwt: String
}

Register

Only the first user will be able to be the admin.

Request
{
  op: "Register",
  data: {
    username: String,
    email: Option<String>,
    password: String,
    password_verify: String,
    admin: bool
  }
}
Response
{
  op: String,
  jwt: String
}

Get User Details

Request
{
  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
{
  op: String,
  user: UserView,
  follows: Vec<CommunityFollowerView>,
  moderates: Vec<CommunityModeratorView>,
  comments: Vec<CommentView>,
  posts: Vec<PostView>,
}

Save User Settings

Request
{
  show_nsfw: bool,
  auth: String,
}
Response
{
  op: String,
  jwt: String
}

Get Replies / Inbox

Request
{
  op: "GetReplies",
  data: {
    sort: String,
    page: Option<i64>,
    limit: Option<i64>,
    unread_only: bool,
    auth: String
  }
}
Response
{
  op: String,
  replies: Vec<ReplyView>,
}

Mark all replies as read

Request
{
  op: "MarkAllAsRead",
  data: {
    auth: String
  }
}
Response
{
  op: String,
  replies: Vec<ReplyView>,
}

Add admin

Request
{
  op: "AddAdmin",
  data: {
    user_id: i32,
    added: bool,
    auth: String
  }
}
Response
{
  op: String,
  admins: Vec<UserView>,
}

Ban user

Request
{
  op: "BanUser",
  data: {
    user_id: i32,
    ban: bool,
    reason: Option<String>,
    expires: Option<i64>,
    auth: String
  }
}
Response
{
  op: String,
  user: UserView,
  banned: bool,
}

Site

List Categories

Request
{
  op: "ListCategories"
}
Response
{
  op: String,
  categories: Vec<Category>
}

Search

Search types are Both, Comments, Posts.

Request
{
  op: "Search",
  data: {
    q: String,
    type_: String,
    community_id: Option<i32>,
    sort: String,
    page: Option<i64>,
    limit: Option<i64>,
  }
}
Response
{
  op: String,
  comments: Vec<CommentView>,
  posts: Vec<PostView>,
}

Get Modlog

Request
{
  op: "GetModlog",
  data: {
    mod_user_id: Option<i32>,
    community_id: Option<i32>,
    page: Option<i64>,
    limit: Option<i64>,
  }
}
Response
{
  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
{
  op: "CreateSite",
  data: {
    name: String,
    description: Option<String>,
    auth: String
  }
}
Response
{
  op: String,
  site: SiteView,
}

Edit Site

Request
{
  op: "EditSite",
  data: {
    name: String,
    description: Option<String>,
    auth: String
  }
}
Response
{
  op: String,
  site: SiteView,
}

Get Site

Request
{
  op: "GetSite"
}
Response
{
  op: String,
  site: Option<SiteView>,
  admins: Vec<UserView>,
  banned: Vec<UserView>,
}

Community

Get Community

Request
{
  op: "GetCommunity",
  data: {
    id: Option<i32>,
    name: Option<String>,
    auth: Option<String>
  }
}
Response
{
  op: String,
  community: CommunityView,
  moderators: Vec<CommunityModeratorView>,
  admins: Vec<UserView>,
}

Create Community

Request
{
  op: "CreateCommunity",
  data: {
    name: String,
    title: String,
    description: Option<String>,
    category_id: i32 ,
    auth: String
  }
}
Response
{
  op: String,
  community: CommunityView
}

List Communities

Request
{
  op: "ListCommunities",
  data: {
    sort: String,
    page: Option<i64>,
    limit: Option<i64>,
    auth: Option<String>
  }
}
Response
{
  op: String,
  communities: Vec<CommunityView>
}

Ban from Community

Request
{
  op: "BanFromCommunity",
  data: {
    community_id: i32,
    user_id: i32,
    ban: bool,
    reason: Option<String>,
    expires: Option<i64>,
    auth: String
  }
}
Response
{
  op: String,
  user: UserView,
  banned: bool,
}

Add Mod to Community

Request
{
  op: "AddModToCommunity",
  data: {
    community_id: i32,
    user_id: i32,
    added: bool,
    auth: String
  }
}
Response
{
  op: String,
  moderators: Vec<CommunityModeratorView>,
}

Edit Community

Mods and admins can remove and lock a community, creators can delete it.

Request
{
  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
{
  op: String,
  community: CommunityView
}

Follow Community

Request
{
  op: "FollowCommunity",
  data: {
    community_id: i32,
    follow: bool,
    auth: String
  }
}
Response
{
  op: String,
  community: CommunityView
}

Get Followed Communities

Request
{
  op: "GetFollowedCommunities",
  data: {
    auth: String
  }
}
Response
{
  op: String,
  communities: Vec<CommunityFollowerView>
}

Post

Create Post

Request
{
  op: "CreatePost",
  data: {
    name: String,
    url: Option<String>,
    body: Option<String>,
    community_id: i32,
    auth: String
  }
}
Response
{
  op: String,
  post: PostView
}

Get Post

Request
{
  op: "GetPost",
  data: {
    id: i32,
    auth: Option<String>
  }
}
Response
{
  op: String,
  post: PostView,
  comments: Vec<CommentView>,
  community: CommunityView,
  moderators: Vec<CommunityModeratorView>,
  admins: Vec<UserView>,
}

Get Posts

Post listing types are All, Subscribed, Community

Request
{
  op: "GetPosts",
  data: {
    type_: String,
    sort: String,
    page: Option<i64>,
    limit: Option<i64>,
    community_id: Option<i32>,
    auth: Option<String>
  }
}
Response
{
  op: String,
  posts: Vec<PostView>,
}

Create Post Like

score can be 0, -1, or 1

Request
{
  op: "CreatePostLike",
  data: {
    post_id: i32,
    score: i16,
    auth: String
  }
}
Response
{
  op: String,
  post: PostView
}

Edit Post

Mods and admins can remove and lock a post, creators can delete it.

Request
{
  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
{
  op: String,
  post: PostView
}

Save Post

Request
{
  op: "SavePost",
  data: {
    post_id: i32,
    save: bool,
    auth: String
  }
}
Response
{
  op: String,
  post: PostView
}

Comment

Create Comment

Request
{
  op: "CreateComment",
  data: {
    content: String,
    parent_id: Option<i32>,
    edit_id: Option<i32>,
    post_id: i32,
    auth: String
  }
}
Response
{
  op: String,
  comment: CommentView
}

Edit Comment

Mods and admins can remove a comment, creators can delete it.

Request
{
  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
{
  op: String,
  comment: CommentView
}

Save Comment

Request
{
  op: "SaveComment",
  data: {
    comment_id: i32,
    save: bool,
    auth: String
  }
}
Response
{
  op: String,
  comment: CommentView
}

Create Comment Like

score can be 0, -1, or 1

Request
{
  op: "CreateCommentLike",
  data: {
    comment_id: i32,
    post_id: i32,
    score: i16,
    auth: String
  }
}
Response
{
  op: String,
  comment: CommentView
}