nutomic/lemmy
Archived
2
0
Fork 1
Code Issues Pull requests Releases Wiki Activity
This repository has been archived on 2020-04-21. You can view files and clone it, but cannot push or open issues or pull requests.
lemmy/docs/api.md
Dessalines d7ab85ab70 Squashed commit of the following: 
commit ecd6c5a2f4
Author: Dessalines <happydooby@gmail.com>
Date:   Tue Aug 13 19:49:38 2019 -0700

    Adding some docs

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

    Adding save user settings

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

    Merge branch 'dev' into nsfw

commit b3d4a5c4ce
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
}