search

inspircd / inspircd-contrib

Third-party InspIRCd module repository.
https://www.inspircd.org
66 stars 72 forks source link

m_httpd_api.cpp a json http api module for inspircd, allows users to query the ircd using json requets and get json response for easy parsing. #275

Closed jnewing closed 5 months ago

jnewing commented 5 months ago

m_httpd_api

Add a nice json api to InspIRCd for easy communication with a web front-end.

Adds the following API requests:

/api/general

Returns a JSON object with some basic general server, network, user and oper information.

Request:

HTTP Method: GET
URI: http(s)://<host>:<port>/api/general
 Headers: 
      Content-Type: application/json
      Token: <token-set-in-config> [required]

Response

{
  "channels": {
    "count": 36
  },
  "opers": {
    "total": 3
  },
  "server": {
    "server_currenttime": 1709326940,
    "server_description": "Awesome InspIRCd Server",
    "server_name": "awesome.server.com",
    "server_network": "XFNet",
    "server_uptime": 1709241048,
    "server_version": "InspIRCd-3.17.0. awesome.server.com :[577] "
  },
  "users": {
    "local": 23,
    "network": 114
  }
}

/api/server

Returns a JSON object containing general information on the server, network, and its uptime.

Request:

HTTP Method: GET
URI: http(s)://<host>:<port>/api/general
 Headers: 
      Content-Type: application/json
      Token: <token-set-in-config> [REQUIRED]

Response:

{
  "server_currenttime": 1709327285,
  "server_description": "Awesome server description.",
  "server_name": "awesome.server.com",
  "server_network": "XFNet",
  "server_uptime": 1709241048,
  "server_version": "InspIRCd-3.17.0. awesome.server.com :[577] "
}

/api/users

Returns JSON array of users matching the given filters, if any. (Filterable)

Request:

HTTP Method: GET | POST
URI: http(s)://<host>:<port>/api/users
Headers:
    Content-Type: application/json
      Token: <token-set-in-config> [REQUIRED]

If filtering with POST request the user must supply the filters JSON object, it can be empty but you can also just use a simpler GET request with no filter data.

Note: You can use multiple filter props (as shown below) and and they will be treated as a logical AND. 

{
  "filters": {
    "ident"   : "some_ident"        ,
    "nickname": "syn*"              ,
    "server"  : "awesome.server.org",
    "oper"    : "SomeOperClass"
  }
}

Response: JSON array of users matching given filters. 

[
  {
    "age": 1709241077,
    "away": {"awaymsg": "", "awaytime": 140720471412536},
    "displayhost": "user.awesomeserver.org",
    "ident": "usersIdent",
    "ipaddress": "127.0.0.1",
    "local": {
      "connectclass": "main",
      "lastmsg": 1709241551,
      "port": 6697,
      "serveraddr": "127.0.0.1:6697"
    },
    "modes": "ios",
    "nickname": "synmuffin",
    "oper": "",
    "realhost": "users.real.host.com",
    "realname": "users_real_name",
    "server": "awesome.server.org",
    "signon": 1709241077,
    "uuid": "467BABAAB"
  },
  ...
]

/api/xlines

Returns a JSON array of xlines, with or without filtering.

Request:

HTTP Method: GET | POST
URI: http(s)://<host>:<port>/api/xlines
Headers:
    Content-Type: application/json
      Token: <token-set-in-config> [REQUIRED]

If filtering with POST request the user must supply the filters JSON object, it can be empty but you can also just use a simpler GET request with no filter data.

Note: You can use multiple filter props (as shown below) and and they will be treated as a logical AND. 

{
  "filters": {
    "type": ["Z", "Q"],
    "mask": "something*"
  }
}

Response:

[
  {
    "duration": 0,
    "duration_string": "0s",
    "mask": "root@*",
    "reason": "Don't IRC as root!",
    "settime": 1709328444,
    "type": "K"
  },
  ...
]

/api/server-list

Returns a list of all servers connected to this network.

Request:

HTTP Method: GET
URI: http(s)://<host>:<port>/api/servers
Headers:
    Content-Type: application/json
    Token: <token-set-in-config> [REQUIRED]

Response:

[
    {
        "latency": 1,
        "parent_name": "second.server.org",
        "server_description": "Awesome Server #2",
        "server_name": "second.server.org",
        "user_count": 12
    },
    {
        "latency": 4,
        "parent_name": "",
        "server_description": "First Server",
        "server_name": "first.server.org",
        "user_count": 56
    }
]

/api/commands

Returns a JSON array list of commands and their use count.

Request:

HTTP Method: GET
URI: http(s)://<host>:<port>/api/commands
Headers:
    Content-Type: application/json
    Token: <token-set-in-config> [REQUIRED]

Response:

[
    {
        "name": "JOIN",
        "use_count": 7
    },
    {
        "name": "KICK",
        "use_count": 3
    },
    ...
]

/api/channels

Returns a JSON array of channels on the server. You can also filter this list by name you can match using glob patterns.

Request:

HTTP Method: GET | POST
URI: http(s)://<host>:<port>/api/channels
Headers:
    Content-Type: application/json
    Token: <token-set-in-config> [REQUIRED]

If filtering with POST request the user must supply the filters JSON object, it can be empty but you can also just use a simpler GET request with no filter data.

{
  "filters": {"name": "#mychannel"}
}

Response:

[
    {
        "channel_modes":  "CFJPSTfnt 3:5 5 4:2",
        "channel_name":  "#mychannel",
        "channel_topic":  "Awesome Server Channel Topic!",
        "set_by":  "synmuffin",
        "set_time":  0,
        "user_count":  9
    },
    ...
]

/api/modules

Returns a JSON array of loaded modules on the server.

Request:

HTTP Method: GET
URI: http(s)://<host>:<port>/api/modules
Headers:
    Content-Type: application/json
    Token: <token-set-in-config> [REQUIRED]

Response:

[
    {
        "description":  "Provides the INVITE, JOIN, KICK, NAMES, and TOPIC commands",
        "name":  "core_channel.so"
    },
    {
        "description":  "Provides support for DNS lookups",
        "name":  "core_dns.so"
    },
    ...
]

/api/motd

Returns a JSON array of the server motd.

Request:

HTTP Method: GET
URI: http(s)://<host>:<port>/api/motd
Headers:
    Content-Type: application/json
    Token: <token-set-in-config> [REQUIRED]

Response:

[
    "Welcome to awesome server.",
    "Please be nice.",
    "Server Info: awesome.server.org",
    "  ",
    "Hostname: awesome.server.org",
    "Happy chatting!"
]