Skip to content

v2 API

Jump to bottom
Robin edited this page Feb 13, 2021 · 82 revisions

This is for pr9+

For pr7 API, go here: https://github.com/NamelessMC/Nameless/wiki/v2-API/8af96b241e0c6a8767c98bc8d190d1847b3ae725

Using the API

In order to use the API, the API key must be verified. This is done by passing the API key within the URL, as follows:

example_site.com/api/v2/API_KEY/action

where API_KEY is the API key used, and action is the specified action.

All UUIDs returned by the API are without dashes. The API accepts UUIDs both with and without dashes as parameters.

The API will also return whether there was an error or not, with the error field (either true or false). If true, there will also be a message field containing the error message.

Actions

info GET

No parameters required. Returns in json format:

  • version - string: NamelessMC version, e.g. 2.0.0-pr8
  • version_update - array:
    • update - whether there is an update available, true or false
    • version - the version for the available update (not present if no update available)
    • urgent - whether the update is urgent (ie a security fix), true or false (not present if no update available)
  • language - Default language
  • modules - array: list of enabled modules

Any suggestions?

getAnnouncements GET

Returns all announcements in json. No parameters required. You can optionally add an id GET parameter so that only announcements the user should see will be returned

{
  "announcements" : [
    {
      "content" : "This is an example announcement",
      "display" : ["Home", "Forums"],
      "permissions" : ["Guests", "Standard", "Moderator"]
    },
    {
      "content" : "This message will be displayed on join by the plugin",
      "display" : ["Plugin", "Vote"],
      "permissions" : ["Guests", "Standard", "Moderator"]
    }
  ],
  "error": false
}

register POST

The register action will register a specified user. POST body is a JSON object with

  • username - Forum username
  • uuid - Minecraft UUID (optional. If Minecraft integration is enabled, the website should get the UUID)
  • email - the email address of the user (must be unique)

If there is an issue with the POST request, the API will display an error containing information about the issue. Otherwise, an email will be sent to the user, asking them to visit the website to complete registration.

TODO: Add error code when minecraft integration is enabled and username is not a minecraft username?

The register method response, if email verification is disabled, is as follows:

{
  "message": "Please click on the following link to complete registration:",
  "link": "http://example.com/complete_signup/?c=CODE",
  "error": false
}

The register method response, if email verification is enabled, is as follows:

{
  "message": "Please check your emails to complete registration.",
  "error": false
}

userInfo GET

The userInfo action will retrieve information about a specified user. Possible GET parameters (choose one):

  • id - NamelessMC id
  • username - NamelessMC username
  • uuid - Minecraft UUID (only if Minecraft integration is enabled)
  • discord_id - Discord user ID

The output is a JSON object containing:

  • exists - Whether an account with the provided username or uuid exists. If this is false, all other fields will be missing.
  • username - the Minecraft username of the user
  • displayname - the custom displayname of the user on the website
  • uuid - the Minecraft UUID of the user (without dashes)
  • registered_timestamp - UNIX timestamp of when the user registered
  • last_online_timestamp
  • banned - whether the user is banned from the website or not (boolean)
  • language - User language, e.g. EnglishUK.
  • validated - (boolean)
  • discord_id - Discord ID, not present if user is not linked with discord
  • groups - Json array of group objects (see below for format)

in 2.1, validated will be replaced by

- `verified` - (boolean)
- `verification`
  - `email` - boolean
  - `minecraft` - boolean
  - `discord` - boolean
  - ...

If ranks are linked with minecraft ranks or discord roles, those will show up as well.

groupInfo GET

id - id of group OR name name of group. Specify multiple times to include multiple groups. When not specified, all groups are listed.

Returns a list of all website groups. New keys may be added later and linked groups like minecraft, discord, may be left out. Staff boolean may be missing as well, in that case assume false.

Always ordered by order, ascending

"groups": [
  {
    "id": 2,
    "name": "Developer",
    "minecraft": "Developer",
    "staff": true,
    "order": 3
  },
  {
    "id": 4,
    "name": "VIP",
    "order": 20
  }
]

addGroups POST

  • user - the NamelessMC ID of the user
  • groups - json array of website group IDs to add to this user

removeGroups POST

  • user - the NamelessMC ID of the user
  • groups - json array of website group IDs to remove from this user

createReport POST

The createReport action will create a report about a given user. The required POST body is a JSON object with the following keys:

  • reporter - NamelessMC user ID of the user creating the report
  • reported - NamelessMC user ID of the user being reported.
  • content - the reason for the report's creation (max 255 characters)

Errors: 19 - Report content too long 16 - reporter or reported invalid 21 - reporter is banned 26 - reporter == reported 23 - unable to create report

getNotifications GET

The getNotifications action will return a list of alerts a user has. Specify the Nameless ID using the id GET parameter.

The method will return error 16 if the user does not exist on the website, otherwise it will return a JSON array with notifications:

Available types:

  • message - A new private message for the user
  • like - Someone has liked a post by the user (coming soon)
  • profile_post - Someone has left a comment on the user's profile
  • profile_post_reply - Someone has replied to a comment on a profile
  • thread-reply - Someone has posted in a thread the user is watching (coming soon)
  • follow - Someone has followed the user (coming soon)
  • Please note that modules may add their own notification types, so your application should be able to handle unknown notification types.
{
    "notifications": [
        "0": {
            "message" : "Samerton has liked your post",
            "url" : "https://example.com/forum/view_topic/?tid=5?post_id=813
            "type" : "like",
        },
        "1": {
            "message" : "Partydragen has left a comment on your profile"
            "url" : "https://example.com/profile/Derkades/354"
            "type" : "profile-comment"
        }
        "2": {
            "message" : "Very important"
            "url" : "https://example.com/something"
            "type" : "message"
        }
    ],
    "error": false
}

serverInfo POST

The serverInfo action is used by the Minecraft plugin to send server information to the website.

The post body is a JSON object:

{
  "max-memory" : 954728448,
  "free-memory" : 344910960,
  "allocated-memory" : 515899392,
  "tps" : 20,
  "server-id" : 3,
  "groups" : [
    "Admin",
    "Developer",
    "Visitor"
  ],
  "players" : {
    "09948878fe2044e3a07242c39869dd1f" : {
      "ip" : "127.0.0.1",
      "name" : "Derkades",
      "groups" : ["Admin", "Builder"],
      "playtime" : 30 (minutes),
      "balance" : 200,
      "location" : {
        "world" : "world",
        "x" : -80,
        "y" : 64,
        "z" : -116
       }
       "placeholders" : {
         "player_level" : "13"
       }
     }
    "2f778755502c4fb7ae96493d6429e8f3" : {
      "ip" : "127.0.0.1",
      "name" : "Samerton",
      "groups" : ["Developer"],
      "balance" : 56,47,
      "location" : {
        "world" : "world",
        "x" : -541,
        "y" : 82,
        "z" : 851
       }
       "placeholders" : {
         "player_level" : "13"
       }
     }
  }
}

Only the server-id field is required, all others are optional. Specifying name for every player is required.

Keep in mind that the requests by the plugin, while they are sent every 10 seconds by default, may be sent more or less frequently.

updateUsername POST

The updateUsername action will update the website username of a user with a given NamelessMC ID. The required JSON object is as follows:

  • user - NamelessMC id
  • username - new username for user

verifyMinecraft POST

  • user - NamelessMC ID
  • code - code to validate user with

listUsers GET

The listUsers action provides a list of registered users. No parameters required. Example response:

{
  "users": [
    {
      "id": 1,
      "username": "Samerton",
      "uuid": "2f778755502c4fb7ae96493d6429e8f3",
      "banned": false,
      "verified": true
    },
    {
      "id": 2,
      "username": "Notch",
      "uuid": "069a79f444e94726a5befca90e38aaf5",
      "banned": false,
      "verified": true
    },
  ],
  "error": false
}

uuid may be left out if Minecraft integration is disabled. Possible filter parameters:

  • banned (boolean)
  • verified (boolean)

submitDiscordRoleList POST

Post body is json object with a key "roles" and value is another json array of objects. Each object has an id and name key for the discord role ID and name, respectively.

updateDiscordBotSettings POST

Updates discord bot settings. Not all parameters below have to be present, it is possible to only change one setting by specifying one parameter.

  • url - New Discord bot URL
  • guild_id - New Discord server ID to be associated with your website (as a string)
  • bot_username Username#1234 of this bot
  • bot_id Discord user ID of the bot (as a string)

errors:

  • 31 if not at least one setting is specified

verifyDiscord POST

Link a discord account with the website. Post body is verification token in plain text.

  • token - Discord verification token
  • discord_id - Discord ID (AS A STRING)
  • discord_username - Discord username

Error codes?

updateDiscordUsernames POST

  • users array of json objects:
    • id discord user id
    • name discord username

Error codes?

getDiscordRoles GET

GET param user (NamelessMC ID). Response roles json array of role ids

Error codes?

setDiscordRoles POST

POST body JSON object:

  • user - NamelessMC id
  • roles - Json array of discord role ids

Error codes?

addDiscordRoles POST

  • user - NamelessMC id
  • roles - discord role ids

removeDiscordRoles POST

  • user - NamelessMC id
  • roles - discord role id. Website will not return an error if the user never had this role ID.

Error Codes

Whenever an error is returned, a code and a message will be returned. The message can be in a variety of languages, depending on the active translation on the website, so the code corresponds to a certain type of error. The error codes and their meaning are listed below.

0 - Unknown error

1 - Invalid API key

2 - Invalid language file

3 - Invalid API method

4 - No unique site ID available

5 - Unable to check for updates

6 - Invalid POST / GET contents

7 - Invalid email address

8 - Invalid username

9 - Invalid UUID

10 - Email already exists

11 - Username already exists

12 - UUID already exists

13 - Unable to create account

14 - Unable to send registration email, please contact an admin to activate your account

15 - cURL error

16 - Unable to find user

17 - Unable to find group

18 - Unable to update user's group

19 - Report content is greater than 255 characters

20 - (not used)

21 - User creating report has been banned from website

22 - User already has an open report regarding the reported player

23 - Unable to create report

24 - Unable to update (Discord or website) username

25 - Unable to update server info

26 - Cannot report youself

27 - Invalid server ID

28 - Invalid validation code

29 - Unable to set user's Discord ID

30 - Unable to set Discord bot URL endpoint

31 - (not used)

32 - User already active

33 - Unable to set Discord Guild ID

34 - Discord integration is disabled

Future Additions

createTopic POST

The createTopic action is used to create a new topic on the website, in a specified forum.

Posting announcements

If you need further help, feel free to join our Discord server for support 😃

Home
Features 🡕

Setup

Installation 🡕
Friendly URLs 🡕
SMTP 🡕
Nameless-Link 🡕

Troubleshooting

FAQ 🡕
Plugin Troubleshooting 🡕

Customization

Modules (v2) 🡕
Templates (v2) 🡕

Development

Modules (v2) 🡕
Templates (v2) 🡕
API (v2) 🡕

Clone this wiki locally