by Max Barry

Latest Forum Topics

Advertisement

2

DispatchMetaReference

by The Dichromatic Mechanism of August. . 186 reads.

NSV Pseudo-API Documentation

Last updated on Saturday, August 28th, 2021. If you find this dispatch helpful, please upvote.


| ABOUT | CREATIVE USES | OPEN SOURCE | NSNEXUS | NSVERIFY | PRIVACY | PSEUDO-API | RMB COMMANDS | STATISTICS | STOCK EXCHANGE |

Overview

This page may be of interest to you if you are a programmer who works with NationStates and Discord, or if you would like to become one.

In general, an Application Programming Interface (API) allows a script or bot to efficiently access data from a website or other remote server. For example, NationStates has an API that provides information about nations, regions, the WA, etc. Scripts typically interact with APIs by making HTTP requests to API endpoints.

NSVerify is a NS verification and role management system for Discord servers, powered by the AugustinAndroid v2 Discord bot.

NSVerify now provides a "pseudo-API" (pAPI) for public use. Rather than by making HTTP requests to a public server (which in this case does not exist), scripts can interact with this pAPI by sending and receiving messages on Discord.

Usage

  1. The user (probably a Discord bot, but could also be a human) sends a message in a channel it shares with AugustinAndroid v2. This message contains a token, an endpoint, and an optional argument. The token, which is needed to match the request with the response, can be any arbitrary string.

  2. AugustinAndroid v2 responds with a message containing the same token and the output data.

  3. The user reads the message and parses the data.

Syntax

Requests

NSV_API_REQUEST [token] [endpoint] [*argument]

Requests always begin with NSV_API_REQUEST. Tokens can be any string, but if you expect to make pAPI calls at high frequency or in busy channels, it is best to make them unique.

Endpoint

Description

Argument

list_discord_accounts

List the IDs of the server members who have verified the given nation.

A nation name, such as August.

list_nations

List the nations verified by a member.

A member's Discord ID, such as 213088304537534464.

list_nations_with_regions

List the nations verified by a server member, along with the last known region for each nation, if any.

A member's Discord ID, such as 213088304537534464.

users_from_region

List the IDs of the server members with verified nations in the given region, if any.

The name of a region, such as Cape of Good Hope.

users_by_region

List all the regions where server members possess verified nations, and list the IDs of the members living in each region.

None.

list_unverified

List the IDs of the server members with no nations verified in the server.

None.

Responses

NSV_API_RESPONSE [token] [data]

Lists are separated with commas. Names are always lowercase, with underscores instead of spaces. If the output is longer than 2000 characters, it will be contained in a text file. If no data is available (eg, a list_nations request for a member with no verified nations), the output is 0.

Endpoint

Output Format Example

list_discord_accounts

213088304537534464

list_nations

august,mercantana,conch_kingdom

list_nations_with_regions

august|cape_of_good_hope,mercantana|lands_end,conch_kingdom|conch_kingdom

users_from_region

228353948552134658,754524576670548049,213088304537534464,293518673417732098

users_by_region

cape_of_good_hope:213088304537534464,311192853684420618
lands_end:831729061399232574,227107561805971456,279767631932948480
conch_kingdom:228353948552134658,754524576670548049,213088304537534464

list_unverified

853073727231361044,717389894921748573,829456280355209287

Limitations

  • The pAPI may only be used on servers, not in private messages. Bots cannot send private messages to other bots anyway, due to Discord limitations.

  • NSVerify must be enabled on the server.

  • Humans may use the pAPI in the exact same way as bots.

  • Users are not subject to any rate limits.

  • Users or servers may be blacklisted by the developer, temporarily or permanently, at any time for any reason. pAPI calls are logged and reviewed by the developer.

  • The same privacy limits that apply to ordinary bot commands also apply to the pAPI.

    • Only publicly verified nations and nations verified on a particular server will be visible on that server.

    • If viewing privately verified nations is limited to server staff (in NSV Settings), a user will only be able to view another user's privately verified nations if he/she/it has a staff role or the Administrator permission.

Future Additions

If you have a request for more features/endpoints, join the LinkAugustinAndroid v2 support server and post in #suggestions. You can also send me a telegram or a private message at August#4079, but there is a much higher chance I will overlook or forget about your suggestion.

RawReport