Merge pull request #11 from SooYou/staging

Added all REST endpoints
plugcommunity · Jul 18, 2015 · 257b523 · 257b523
2 parents 2ced688 + f299bdb
commit 257b523
Show file tree

Hide file tree

Showing 57 changed files with 3,303 additions and 0 deletions.
diff --git a/README.md b/README.md
@@ -44,6 +44,8 @@ patched or fixed.
 * houdhakker2
 * IgorAntun
 * Marvin (xBytez)
+* René Kooi (goto-bus-stop)
+* SooYou
 
 Thank you for making this project possible by contributing!
 

diff --git a/api/endpoints/README.md b/api/endpoints/README.md
@@ -0,0 +1,76 @@
+### Introduction
+
+The plug API is seperated into two systems, 
+[WebSocket](https://github.com/plugcommunity/documentation/tree/master/api/events) and 
+[REST](#).
+While the WebSocket part is used to communicate at real time (such as chat, booth advancement etc.), the REST API is 
+used to do everything that does not require a real time connection. While this certainly induces a bit of latency
+for each action, it is something that can be easily handled with.
+
+
+### Tips and tricks
+
+One thing to mention is that you can only send a limited amount of request in a certain timespan, if you overdo it 
+for a longer amount of time you'll be banned. This can certainly happen when you decide to to delete
+a bunch of chat messages without artifically slowing the amount of requests down.
+
+### List of endpoints
+
+| Endpoint Name             | Link                                                                                     |
+|-----------------------    | -------------                                                                            |
+| Auth Facebook             | "[auth/facebook]                 (/api/endpoints/auth_facebook.md)"                      |
+| Auth Login                | "[auth/login]                    (/api/endpoints/auth_login.md)"                         |
+| Auth Reset                | "[auth/reset/me]                 (/api/endpoints/auth_reset_me.md)"                      |
+| Auth Session              | "[auth/session]                  (/api/endpoints/auth_session.md)"                       |
+| Bans                      | "[bans]                          (/api/endpoints/bans.md)"                               |
+| Bans Add                  | "[bans/add]                      (/api/endpoints/bans_add.md)"                           |
+| Booth                     | "[booth]                         (/api/endpoints/booth_md)"                              |
+| Booth Add                 | "[booth/add]                     (/api/endpoints/booth_add.md)"                          |
+| Booth Cycle               | "[booth/cycle]                   (/api/endpoints/booth_cycle.md)"                        |
+| Booth Lock                | "[booth/lock]                    (/api/endpoints/booth_lock.md)"                         |
+| Booth Move                | "[booth/move]                    (/api/endpoints/booth_move.md)"                         |
+| Booth Remove              | "[booth/remove/:id]              (/api/endpoints/booth_remove.md)"                       |
+| Booth Skip                | "[booth/skip]                    (/api/endpoints/booth_skip.md)"                         |
+| Booth Skip Me             | "[booth/skip/me]                 (/api/endpoints/booth_skip_me.md)"                      |
+| Chat Delete               | "[chat/:cid]                     (/api/endpoints/chat_cid.md)"                           |
+| Friends                   | "[friends]                       (/api/endpoints/friends.md)"                            |
+| Friends Ignore            | "[friends/ignore]                (/api/endpoints/friends_ignore.md)"                     |
+| Friends Invites           | "[friends/invites]               (/api/endpoints/friends_invites.md)"                    |
+| Grabs                     | "[grabs]                         (/api/endpoints/grabs.md)"                              |
+| Ignores                   | "[ignores]                       (/api/endpoints/ignores.md)"                            |
+| Mutes                     | "[mutes]                         (/api/endpoints/mutes.md)"                              |
+| News                      | "[news]                          (/api/endpoints/news.md)"                               |
+| Playlists                 | "[playlists]                     (/api/endpoints/playlists.md)"                          |
+| Playlists Activate        | "[playlists/:id/activate]        (/api/endpoints/playlists_id_activate.md)"              |
+| Playlists Media Delete    | "[playlists/:id/media/delete]    (/api/endpoints/playlists_id_media_delete.md)"          |
+| Playlists Media Insert    | "[playlists/:id/media/insert]    (/api/endpoints/playlists_id_media_insert.md)"          |
+| Playlists Media Move      | "[playlists/:id/media/move]      (/api/endpoints/playlists_id_media_move.md)"            |
+| Playlists Media Update    | "[playlists/:id/media/update]    (/api/endpoints/playlists_id_media_update.md)"          |
+| Playlists Rename          | "[playlists/:id/rename]          (/api/endpoints/playlists_id_rename.md)"                |
+| Playlists Shuffle         | "[playlists/:id/shuffle]         (/api/endpoints/playlists_id_shuffle.md)"               |
+| Playlists Media           | "[playlists/:id/media]           (/api/endpoints/playlists_id_media.md)"                 |
+| Profile Blurb             | "[profile/blurb]                 (/api/endpoints/profile_blurb.md)"                      |
+| Rooms                     | "[rooms]                         (/api/endpoints/rooms.md)"                              |
+| Rooms Favorites           | "[rooms/favorites]               (/api/endpoints/rooms_favorites.md)"                    |
+| Rooms History             | "[rooms/history]                 (/api/endpoints/rooms_history.md)"                      |
+| Rooms Join                | "[rooms/join]                    (/api/endpoints/rooms_join.md)"                         |
+| Rooms Me                  | "[rooms/me]                      (/api/endpoints/rooms_me.md)"                           |
+| Rooms State               | "[rooms/state]                   (/api/endpoints/rooms_state.md)"                        |
+| Rooms Update              | "[rooms/update]                  (/api/endpoints/rooms_update.md)"                       |
+| Rooms Validate            | "[rooms/validate]                (/api/endpoints/rooms_validate.md)"                     |
+| Staff                     | "[staff]                         (/api/endpoints/staff.md)"                              |
+| Staff Update              | "[staff/update]                  (/api/endpoints/staff_update.md)"                       |
+| Store Inventory           | "[store/inventory]               (/api/endpoints/store_inventory.md)"                    |
+| Store Products            | "[store/products]                (/api/endpoints/store_products.md)"                     |
+| Store Purchase            | "[store/purchase]                (/api/endpoints/store_purchase.md)"                     |
+| Store Purchase Username   | "[store/purchase/username]       (/api/endpoints/store_purchase_username.md)"            |
+| Users                     | "[users]                         (/api/endpoints/users.md)"                              |
+| Users Avatar              | "[users/avatar]                  (/api/endpoints/users_avatar.md)"                       |
+| Users Bulk                | "[users/bulk]                    (/api/endpoints/users_bulk.md)"                         |
+| Users Language            | "[users/language]                (/api/endpoints/users_language.md)"                     |
+| Users Me                  | "[users/me]                      (/api/endpoints/users_me.md)"                           |
+| Users Me History          | "[users/me/history]              (/api/endpoints/users_me_history.md)"                   |
+| Users Me Transactions     | "[users/me/transactions]         (/api/endpoints/users_me_transactions.md)"              |
+| Votes                     | "[votes]                         (/api/endpoints/votes.md)"                              |
+
+*Ordered by Endpoint Name^
diff --git a/api/endpoints/auth_facebook.md b/api/endpoints/auth_facebook.md
@@ -0,0 +1,38 @@
+# auth/facebook Endpoint
+
+The auth/facebook endpoint logs you into the plug.dj service.
+
+**Note**: This sets the **pw** member in your state data to false
+
+### Endpoint
+
+**auth/facebook**
+
+### available verbs
+
+_POST_
+
+### Parameters
+
+**csrf**: Cross Site Request Forgery token
+**accessToken**: Access token given by facebook.com
+**userID**: userID given by facebook.com
+
+```json
+{
+    "csrf": "xxxxx",
+    "accessToken": "xxx", 
+    "userID": "xxx"
+}
+```
+
+### Data returned
+
+```js
+{
+    'data': [],
+    'meta': {},
+    'status': 'ok',
+    'time': 'xx.xxxxxxxxxxx'
+}
+```
diff --git a/api/endpoints/auth_login.md b/api/endpoints/auth_login.md
@@ -0,0 +1,56 @@
+# auth/login Endpoint
+
+The auth/login endpoint logs you into the plug.dj service.
+
+### Endpoint
+
+**auth/login**
+
+### available verbs
+
+_POST_
+
+### Parameters
+
+**csrf**: Cross Site Request Forgery token
+**email**: Your email
+**password**: Your password
+
+```json
+{
+    "csrf": "xxxxx",
+    "email": "[email protected]",
+    "password": "xxx"
+}
+```
+
+### Possible error messages
+
+CSRF token is invalid
+```json
+{
+    "data": [
+        "This CSRF token has expired."
+    ],
+    "status": "csrfTokenExpired",
+}
+```
+
+Email or password aren't correct
+```json
+{
+    "data": [],
+    "status": "badLogin",
+}
+```
+
+### Data returned
+
+```js
+{
+    'data': [],
+    'meta': {},
+    'status': 'ok',
+    'time': 'xx.xxxxxxxxxxx'
+}
+```
diff --git a/api/endpoints/auth_reset_me.md b/api/endpoints/auth_reset_me.md
@@ -0,0 +1,22 @@
+# auth/reset/me Endpoint
+
+The auth/reset/me endpoint will invalidate your login.
+
+### Endpoint
+
+**auth/reset/me**
+
+### available verbs
+
+_POST_
+
+### Data returned
+
+```js
+{
+    'data': [],
+    'meta': {},
+    'status': 'ok',
+    'time': 'xx.xxxxxxxxxxx'
+}
+```
diff --git a/api/endpoints/auth_session.md b/api/endpoints/auth_session.md
@@ -0,0 +1,22 @@
+# auth/session Endpoint
+
+The auth/session endpoint enables you to log out of plug.
+
+### Endpoint
+
+**auth/session**
+
+### available verbs
+
+_DELETE_
+
+### Data returned
+
+```js
+{
+    'data': [],
+    'meta': {},
+    'status': 'ok',
+    'time': 'xx.xxxxxxxxxxx'
+}
+```
diff --git a/api/endpoints/bans.md b/api/endpoints/bans.md
@@ -0,0 +1,56 @@
+# bans Endpoint
+
+The bans endpoint retrieves a list of active bans.
+
+**Note**: You need to have sufficient permissions in the room to access this resource, otherwise you'll just be greeted
+with a requestError status.
+
+**Reason**: The reason member is set as a single number which represent the following reasons:
+**1**: (VIOLATING_COMMUNITY_RULES) User violated the community rules
+**2**: (VERBAL_ABUSE) User was harsh to other community members
+**3**: (SPAMMING) User spammed the chat
+**4**: (OFFENSIVE_LANGUAGE) User was using offensive language
+**5**: (NEGATIVE_ATTITUDE) User was having a negative attitude towards others
+
+**BanDuration**: The duration member can have the following values:
+**f**: User is banned permanently
+**d**: User is banned for a day
+**h**: User is banned for an hour
+
+### Endpoint
+
+**bans**
+
+### available verbs
+
+_GET_
+
+### Possible error messages
+
+Insufficient permissions
+```json
+{
+    "data": [
+        "You are not authorized to access this resource."
+    ],
+    "status": "notAuthorized",
+}
+```
+
+### Data returned
+
+```js
+{
+    'data': [{                  // Contains the requested data
+        'duration': 'x',        // See BanDuration above
+        'moderator': 'xxxx',    // Name of the moderator
+        'reason': 1,            // Reason why they got banned. See BanReason above
+        'id': -1,               // ID of the user
+        'timestamp': 'xxx',     // Date when the ban became active
+        'username': 'xxxx'      // Name of the user
+    }],
+    'meta': {},
+    'status': 'ok',
+    'time': 'xx.xxxxxxxxxxx'
+}
+```
diff --git a/api/endpoints/bans_add.md b/api/endpoints/bans_add.md
@@ -0,0 +1,90 @@
+# bans/add Endpoint
+
+The bans/add endpoint enables you to ban a user.
+
+**Note**: You need to have sufficient permissions in the room to access this resource.
+
+**Reason**: The reason member is set as a single number which represent the following reasons:
+**1**: (VIOLATING_COMMUNITY_RULES) User violated the community rules
+**2**: (VERBAL_ABUSE) User was harsh to other community members
+**3**: (SPAMMING) User spammed the chat
+**4**: (OFFENSIVE_LANGUAGE) User was using offensive language
+**5**: (NEGATIVE_ATTITUDE) User was having a negative attitude towards others
+
+**BanDuration**: The duration member can have the following values:
+**f**: User is banned permanently
+**d**: User is banned for a day
+**h**: User is banned for an hour
+
+### Endpoint
+
+**bans/add**
+
+### available verbs
+
+_POST_
+
+### Parameters
+
+**userID**: ID of the user you want to move
+**reason**: The reason why the user got banned
+**duration**: The duration of the ban
+
+```json
+{
+    "userID": -1,
+    "reason": 1,
+    "duration": "x"
+}
+```
+
+### Possible error messages
+
+Insufficient permissions
+```json
+{
+    "data": [
+        "You are not authorized to access this resource."
+    ],
+    "status": "notAuthorized",
+}
+```
+
+Wrong userID
+```json
+{
+    "data": [],
+    "status": "requestError",
+}
+```
+
+Wrong duration time
+```json
+{
+    "data": [
+        "Not a valid ban duration"
+    ],
+    "status": "requestError",
+}
+```
+
+reason or userID is missing
+```json
+{
+    "data": [
+        "xxxxxxxx is required"
+    ],
+    "status": "requestError",
+}
+```
+
+### Data returned
+
+```js
+{
+    'data': [],
+    'meta': {},
+    'status': 'ok',
+    'time': 'xx.xxxxxxxxxxx'
+}
+```