Skip to content

Improve documentation #1

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
EndBug wants to merge 2 commits into
base: master
Choose a base branch
from
Open

Improve documentation #1

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
6303927
docs: improve formatting
EndBug Jan 17, 2021
66cec92
docs: update docs
EndBug Jan 17, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
58 changes: 30 additions & 28 deletions docs/api/fetch-data.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,51 +1,53 @@
# Fetch informations

### IMPORTANT
**Please make sure to read the introduction before request help !**

*Fetching data must be do with a GET request*
**Please make sure to read the introduction before request help !**
_Fetching data must be done with a GET request_

##### fetch global statistics about a bot
## Fetch global statistics about a bot

`GET /bots/:botID/`

Response:

`GET /bots/:botID/`<br>
**Output:**
```json
{
"name":"mybot#0000",
"id":"000000000",
"avatar":"https://cdn.discordapp.com/avatars/id/avatar.png",
"prefix":"!",
"library":"library",
"owner":"exemple#0000",
"ownerid":"00000000000",
"short_desc":"The short desc",
"long_desc":"the bot's description",
"tags":["music", "info", "traffic"],
"support":"https://discord.gg/support",
"website":"https://bladebotlist.xyz",
"github":"https://github.com/bladebotlist",
"servers":"n/a or a number",
"status":"approved/waiting/declined",
"votes": "number",
"certified": "boolean"
"name": "mybot#0000",
"id": "000000000",
"avatar": "https://cdn.discordapp.com/avatars/id/avatar.png",
"prefix": "!",
"library": "library",
"owner": "exemple#0000",
"ownerid": "00000000000",
"short_desc": "The short desc",
"long_desc": "the bot's description",
"tags": ["music", "info", "traffic"],
"support": "https://discord.gg/support",
"website": "https://bladebotlist.xyz",
"github": "https://github.com/bladebotlist",
"servers": "n/a or a number",
"status": "approved/waiting/declined",
"votes": "number",
"certified": "boolean"
}
```

##### Fetch a array of bots in the botlist
## Fetch a array of bots in the botlist

`GET /bots`

**PRIVATE ENDPOINT**

##### Fetch if a user has voted for a bot
## Fetch if a user has voted for a bot

`GET /bots/:botID/votes/:userID`

**Output:**
Response:

```json
{
"voted":"boolean",
"votes":"number of votes"
"voted": "boolean",
"votes": "number of votes"
}
```

19 changes: 11 additions & 8 deletions docs/api/introduction.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,21 +1,24 @@
# Introduction
### Reference
**To interact with the bladebotlist api you will need these things**
#### Base urls

`https://bladebotlist.xyz/api/` **-** [Current] [Working]
## Reference

### Base urls

`https://bladebotlist.xyz/api/` **-** [Current][working]

### Authentication
#### **Why need authorization ?**
*For security reasons we need to make some endpoints only accessible while you add a authorization token on headers*

#### **Why do I need authorization?**

_For security reasons we need to make some endpoints only accessible while you add a authorization token on headers._

**Example:**
| Header | Value |
|---|---|
| **Authorization** | `MyPowerFulAPIkeyToBeAuthenitificated` |

### Bot Statistics
*We highly recommands you to use our [**NPM MODULE**](https://npmjs.com/package/bbl-api) this will make data posting easier*

**Posting data is also recommanded for big bots and bots which want to be [certified](https://bladebotlist.xyz/certify)**
_We highly recommands you to use our [**NPM MODULE**](https://npmjs.com/package/bbl-api), this will make data posting easier._

**Posting data is also recommanded for big bots and bots which want to be [certified](https://bladebotlist.xyz/certify).**
39 changes: 17 additions & 22 deletions docs/api/post-data.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,39 +1,34 @@
# Post informations

## Using module
## Using our module

**READ MODULE'S DOCS**
Read the package docs before using it!
[NODE.js Module](https://www.npmjs.com/package/bbl-api)

## Posting manually

### Manual post
### Headers

#### Important
| Key | Value |
| ------------- | ---------------- |
| Authorization | Bot's API KEY |
| Content-Type? | application/json |

Things with \* are mandatory
### Body

**Please add these things in headers**
| Key | Value |
| ------------ | ---------------------------- |
| server_count | number of servers |
| shard_count? | number of shards, if sharded |

| Key | Value |
|---|---|
| authorization* | Bot's API KEY |
| Content-Type | application/json |

**Please add these things in body __as json__**

| Key | Value |
|---|---|
| servercount* | number of servers |
| shardcount | number of shards if sharded |

**Then you will need to do this request**
### Endpoint

`POST /bots/:botID/stats`

*Output:*<br>
### Response

```json
{
ok:"successfully posted servercount servers for the bot botname !"
"ok": "successfully posted servercount servers for the bot botname !"
}
```
```
162 changes: 85 additions & 77 deletions docs/api/using-webhooks.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,125 +5,133 @@
### Create the webhook

1. Go to server settings
![server settings](http://cdn.bladebotlist.xyz/SDcWC1MX)
![server settings](http://cdn.bladebotlist.xyz/SDcWC1MX)
2. Go to Integrations
![integrations](http://cdn.bladebotlist.xyz/aVpU3C6l)
![integrations](http://cdn.bladebotlist.xyz/aVpU3C6l)
3. Click on "Create Webhook"
![create webhook](http://cdn.bladebotlist.xyz/FwWo8791)
![create webhook](http://cdn.bladebotlist.xyz/FwWo8791)
4. Edit the name (1), The channel (2) and the avatar (3)
![Edut name, channel, avatar](http://cdn.bladebotlist.xyz/UZ87O0Vu)
![Edut name, channel, avatar](http://cdn.bladebotlist.xyz/UZ87O0Vu)
5. And finally copy the webhook url
![Copy webhook](http://cdn.bladebotlist.xyz/d1Jk5KFG)
![Copy webhook](http://cdn.bladebotlist.xyz/d1Jk5KFG)
6. If you did everything you must got an url like `https://discord.com/api/webhooks/000111222333444555/T0K3EN`

### Add it to BladeBotList

1. Go to `https://bladebotlist.xyz/bot/:YOURBOTID/edit/webhook`
![Bot Webhook page](http://cdn.bladebotlist.xyz/LDEOkqIU)
![Bot Webhook page](http://cdn.bladebotlist.xyz/LDEOkqIU)
2. Paste the webhook url in the "Discord Webhook" field
![Bot webhook](http://cdn.bladebotlist.xyz/xo1N86cf)
![Bot webhook](http://cdn.bladebotlist.xyz/xo1N86cf)
3. Click on "Edit Webhook" and you're done !
![Edit webhook](http://cdn.bladebotlist.xyz/J2lVoD8e)
![Edit webhook](http://cdn.bladebotlist.xyz/J2lVoD8e)
4. Test it by voting for the bot !
![Vote demo](http://cdn.bladebotlist.xyz/TT0TMge7)

![Vote demo](http://cdn.bladebotlist.xyz/TT0TMge7)

## Post to Custom Webhook server

### Using the BBL-API module

[Default config](https://github.com/BladeBotList/bbl-api/blob/master/examples/postdata.js)
```js

const BBL = require("../app");
```js
const BBL = require('../app');
const client = new BBL(
"", // BOT_ID
"", // API_KEY,
{
server_count: "20", // number of servers ie: discordjs v12 => client.guilds.cache.size
shard_count: "0", // number of shards, null if not defined
interval: 300000, // interval bethween each post
});
'', // BOT_ID
'', // API_KEY,
{
server_count: '20', // number of servers ie: discordjs v12 => client.guilds.cache.size
shard_count: '0', // number of shards, null if not defined
interval: 300000, // interval bethween each post
}
);

client.on('ready', () => console.log('Client is started !')); // when the module is loaded and ready to post data

client.on("ready", () => console.log("Client is started !")); // when the module is loaded and ready to post data
client.on('debug', log => console.log(log)); // debug messages for developers, not required

client.on("debug", (log) => console.log(log)) // debug messages for developers, not required
client.on('update', () => console.log('Stats updated !')); // event when autopost or manual post

client.on("update", () => console.log("Stats updated !")); // event when autopost or manual post

client.on("error", (error) => console.log(`Something was wrong when the module has posted stats: ${error}`)); // complete reports about errors like invalid api key or bot id
client.on('error', error => console.log(
`Something was wrong when the module has posted stats: ${error}`
)); // complete reports about errors like invalid api key or bot id
```

1. Add in the module config this:

```json
webhook: {
status: true,
port: 6060,
password: "youshallnotpass",
endpoint:"/hook"
}
"webhook": {
"status": true,
"port": 6060,
"password": "youshallnotpass",
"endpoint": "/hook"
}
```

2. Change the port if need (default: 3000)
3. Change the password or left empty to disable (Not recommanded at all) (default: none)
4. Change the endpoint if you want (default: /hook)
5. [Final code](https://github.com/BladeBotList/bbl-api/blob/master/examples/webhooks.js)

```js
const BBL = require("../app");
const BBL = require('../app');
const client = new BBL(
"", // BOT_ID
"", // API_KEY,
{
server_count: "3000",
shard_count: "20",
interval: 300000,
webhook: {
status: true,
port: 6060,
password: "youshallnotpass",
endpoint:"/hook"
}
});


client.on("ready", () => console.log("Client is started !")); // when the module is loaded and ready to post data

client.on("debug", (log) => console.log(log))

client.on("update", () => console.log("Stats updated !")); // autopost or manual post

client.on("error", (error) => console.log(`Something was wrong when the module has posted stats: ${error}`)); // complete reports about errors like invalid api key or bot id

client.on("vote", (out) => {
/*
out must looks like
{
"userid":355995885085392896,
"usertag":`HiiZun#0001`,
"username":`HiiZun`,
"userdiscriminator":`0001`,
"botID":`643499304950038539`,
"date":1603908629750
}
*/

console.log(`Whoohoo ! ${out.usertag} just voted !`)
})
'', // BOT_ID
'', // API_KEY,
{
server_count: '3000',
shard_count: '20',
interval: 300000,
webhook: {
status: true,
port: 6060,
password: 'youshallnotpass',
endpoint: '/hook',
},
}
);

client.on('ready', () => console.log('Client is started !')); // when the module is loaded and ready to post data

client.on('debug', log => console.log(log));

client.on('update', () => console.log('Stats updated !')); // autopost or manual post

client.on('error', error => console.log(
`Something was wrong when the module has posted stats: ${error}`
)); // complete reports about errors like invalid api key or bot id

client.on('vote', out => {
/*
`out` must looks like this:
{
"userid":355995885085392896,
"usertag":`HiiZun#0001`,
"username":`HiiZun`,
"userdiscriminator":`0001`,
"botID":`643499304950038539`,
"date":1603908629750
}
*/

console.log(`Whoohoo ! ${out.usertag} just voted !`);
});
```
6. the event "vote" is emitted when you receve a bot

6. the event "vote" is emitted when you receve a bot

7. Go to `https://bladebotlist.xyz/bot/:BOTID/edit/webhook`, and put url as: `http://<serverIP>:<port>/<endpoint>` ex: http://mybot.bladebotlist.xyz:6060/hook
![Example](http://cdn.bladebotlist.xyz/PfgIV682)
![Example](http://cdn.bladebotlist.xyz/PfgIV682)
8. Add the password if you added it (you can seee it by clicking on "show password")
![Password example](http://cdn.bladebotlist.xyz/HDuEaSR5)
![Password example](http://cdn.bladebotlist.xyz/HDuEaSR5)
9. And finally test !
![](http://cdn.bladebotlist.xyz/XDIwUSSV)
![](http://cdn.bladebotlist.xyz/XDIwUSSV)

### Using custom Webserver/Library/Code

**We don't give support for custom webhooks**

__Informations:__
- Requests are made as POST
- we proivde password in headers
- data is in the body
**Informations:**

- Requests are made as POST
- we proivde password in headers
- data is in the body
2 changes: 1 addition & 1 deletion package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@
"lint": "eslint . --ext js,md,vue",
"serve": "vuepress dev docs",
"build": "NODE_ENV=production vuepress build docs",
"devbuild":"vuepress build docs"
"devbuild": "vuepress build docs"
},
"repository": "https://github.com/bladebotlist/docs.git",
"author": "HiiZun",
Expand Down