diff --git a/README.md b/README.md index 5ff7e97..9f6cdd6 100644 --- a/README.md +++ b/README.md @@ -12,3 +12,145 @@ Distributes users onto different classes, each had its own permissions ## Libraries editormd + +## Cavern API Quick Start +To get data from Cavern, a recommended way is to use the **Cavern API**. + +Following are 2 commonly used api endpoints to create a viewer for the Cavern website. + +- [Posts](#Posts) +- [User Profile](#User-Profile) + +To see full documentation, please visit [reference](reference.md). + +### Posts +#### Posts list +In order to get posts, the following endpoint is used +``` +/ajax/posts.php +``` +The reponse of the api call contains +- fetch series(```fetch```) +- number of posts(```page_limit```) +- current page(```page```) +- number of all posts(```all_posts_count```) +- posts list(```posts```) + +and each post inside posts list contains +- author's username(```author```) +- author's displayed name(or nickname)(```name```) +- the PID of the post(```pid```) +- the title of the post(```title```) +- the time when the post is sent(```time```) +- the number of likes the post received(```likes_count```) +- the number of comments about the post(```comments_count```) +- whether the current user has liked it(*note: if it isn't logged, the result will be false*)(```islike```) + +```json +{ + "fetch":1570115846126, + "page_limit":1, + "page":3, + "all_posts_count":200, + "posts": + [ + { + "author":"ExampleAuthor", + "name":"AuthorName", + "pid":300, + "title":"ExampleTitle", + "time":"2019-08-29 13:00:00", + "likes_count":"1", + "comments_count":"3", + "islike":false + + } + ] +} +``` +To change the number of posts you want to receive or current page, you can specify the ```limit``` and ```page``` arguments. + +``` +/ajax/posts.php?limit={number of posts}&&page={page number} +``` + +#### Post Content of a Specific PID +To get an post's content, you must access it with its PID. +``` +/ajax/posts.php?pid={PID} +``` +The response contains +- fetch series(```fetch```) +- post content(```post```) + +The body of post contains +- author's username(```author```) +- author's diaplyed name(or nickname)(```name```) +- the title of the post(```title```) +- the content of the post(```content```) +- the time when the post is sent(```time```) +- the number of likes the post received(```likes_count```) +- the number of comments about the post(```comments_count```) +- whether the current user has liked it(*note: if it isn't logged in, the result will be false*)(```islike```) + +```json +{ + "fetch":1570117194098, + "post": + { + "author":"ExampleAuthor", + "name":"ExampleAuthorName", + "title":"ExampleTitle", + "content":"ExampleContent", + "time":"2019-06-01 12:00:00", + "likes_count":"0", + "comments_count":"10", + "islike":false + } +} +``` + +### User Profile + +#### User's level +In Cavern API, we use different level number to represent the ability to access resources and functionality. +The following table is the level numbers and its permissions. + +Level | Displayed Name | View post | Comment | Like | Receive notification | Create new posts | Edit posts | Delete posts | +------ | ------------------- | ------------ | ----------- | ----- | ---------------------- | -------------------- | ------------| ------------- +0 | 會員 | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ +1 | 作者 | ✅ | ✅ | ✅ | ✅ | ✅ | him/herself | him/herself | him/herself | +8 | 管理員 | ✅ | ✅ | ✅ | ✅ | ✅ | all | all | all +9 | 站長 | ✅ | ✅ | ✅ | ✅ | ✅ | all | all | all + +#### Get User's Profile with a Specific Username +Use the following endpoint to get a user's profile with a specific username. +``` +/ajax/user.php?username={username} +``` +The response contains +- the username(```username```) +- the displayed name(```name```) +- user's level number(```level```) +- displayed name of the user's level number(*note: in unicode*)(```role```) +- the hash value of the user's email(*for surcurity reason, Cavern API won't provide developers with user's email*)(```hash```) +- whether the user is muted(```muted```) +- the number of posts the user created(```posts_count```) +- whether **you** are in a logged in state(```login```) +- fetch series(```fetch```) + +```json +{ + "username":"ExampleUsername", + "name":"ExampleName", + "level":8, + "role":"\u7ba1\u7406\u54e1", + "hash":"32c018e02c34cf3fddfbebba6b44c5fc", + "muted":false, + "posts_count":25, + "login":false, + "fetch":1570285748411 +} +``` + +Again, to see full documentation, please visit our [reference](reference.md) diff --git a/reference.md b/reference.md new file mode 100644 index 0000000..e69de29