NSV Pseudo-API Documentation

[i]Last updated on Saturday, August 28th, 2021. If you find this dispatch helpful, please upvote.[/i]
[img]https://i.imgur.com/allfD5l.png[/img]
[hr][font=palatino][size=160][color=black] | [/color][/size][url=page=dispatch/id=1257698][color=black][size=160]A[/size][size=120]BOUT[/size][/color][/url][size=160][color=black] | [/color][/size][url=page=dispatch/id=1316771][color=black][size=160]C[/size][size=120]REATIVE [/size][size=160]U[/size][size=120]SES[/size][/color][/url][size=160][color=black] | [/color][/size][url=page=dispatch/id=1430919][color=black][size=160]O[/size][size=120]PEN [/size][size=160]S[/size][size=120]OURCE[/size][/color][/url][size=160][color=black] | [/color][/size][url=page=dispatch/id=1297396][color=black][size=160]NSN[/size][size=120]EXUS[/size][/color][/url][size=160][color=black] | [/color][/size][url=page=dispatch/id=1172824][color=black][size=160]NSV[/size][size=120]ERIFY[/size][/color][/url][size=160][color=black] | [/color][/size][url=page=dispatch/id=1498853][color=black][size=160]P[/size][size=120]RIVACY[/size][/color][/url][size=160][color=black] | [/color][/size][u][b][url=page=dispatch/id=1581128][color=black][size=160]P[/size][size=120]SEUDO-[/size][size=160]API[/size][/color][/url][/b][/u][size=160][color=black] | [/color][/size][url=page=dispatch/id=1585568][color=black][size=160]RMB [/size][size=160]C[/size][size=120]OMMANDS[/size][/color][/url][size=160][color=black] | [/color][/size][url=page=dispatch/id=1432339][color=black][size=160]S[/size][size=120]TATISTICS[/size][/color][/url][size=160][color=black] | [/color][/size][url=page=dispatch/id=1560090][color=black][size=160]S[/size][size=120]TOCK [/size][size=160]E[/size][size=120]XCHANGE[/size][/color][/url][size=160][color=black] | [/color][/size][/font][hr]

[size=140][b]Overview[/b][/size]

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 [url=https://www.nationstates.net/pages/api.html]API[/url] that provides information about nations, regions, the WA, etc. Scripts typically interact with APIs by making HTTP requests to API endpoints.

[url=https://www.nationstates.net/page=dispatch/id=1172824]NSVerify[/url] is a NS verification and role management system for Discord servers, powered by the [url=https://www.nationstates.net/page=dispatch/id=1257698]AugustinAndroid v2[/url] 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.

[size=140][b]Usage[/b][/size]

[list=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.
[*]AugustinAndroid v2 responds with a message containing the same token and the output data.
[*]The user reads the message and parses the data.[/list]
[center][img]https://i.imgur.com/Zo0gOrQ.png[/img][/center]

[size=140][b]Syntax[/b][/size]

[u]Requests[/u]

[font=courier]NSV_API_REQUEST [token] [endpoint] [*argument][/font]

Requests always begin with [font=courier]NSV_API_REQUEST[/font]. 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.

[table][tr][td]Endpoint[/td][td]Description[/td][td]Argument[/td][/tr][tr][td]list_discord_accounts[/td][td]List the IDs of the server members who have verified the given nation.[/td][td]A nation name, such as August.[/td][/tr][tr][td]list_nations[/td][td]List the nations verified by a member.[/td][td]A member's Discord ID, such as 213088304537534464.[/td][/tr][tr][td]list_nations_with_regions[/td][td]List the nations verified by a server member, along with the last known region for each nation, if any.[/td][td]A member's Discord ID, such as 213088304537534464.[/td][/tr][tr][td]users_from_region[/td][td]List the IDs of the server members with verified nations in the given region, if any.[/td][td]The name of a region, such as Cape of Good Hope.[/td][/tr][tr][td]users_by_region[/td][td]List all the regions where server members possess verified nations, and list the IDs of the members living in each region.[/td][td]None.[/td][/tr][tr][td]list_unverified[/td][td]List the IDs of the server members with no nations verified in the server.[/td][td]None.[/td][/tr][/table]

[u]Responses[/u]

[font=courier]NSV_API_RESPONSE [token] [data][/font]

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 [font=courier]list_nations[/font] request for a member with no verified nations), the output is [font=courier]0[/font].

[table][tr][td]Endpoint[/td][td]Output Format Example[/td][/tr][tr][td]list_discord_accounts[/td][td]213088304537534464[/td][/tr][tr][td]list_nations[/td][td]august,mercantana,conch_kingdom[/td][/tr][tr][td]list_nations_with_regions[/td][td]august|cape_of_good_hope,mercantana|lands_end,conch_kingdom|conch_kingdom[/td][/tr][tr][td]users_from_region[/td][td]228353948552134658,754524576670548049,213088304537534464,293518673417732098[/td][/tr][tr][td]users_by_region[/td][td]cape_of_good_hope:213088304537534464,311192853684420618
lands_end:831729061399232574,227107561805971456,279767631932948480
conch_kingdom:228353948552134658,754524576670548049,213088304537534464[/td][/tr][tr][td]list_unverified[/td][td]853073727231361044,717389894921748573,829456280355209287[/td][/tr][/table]

[size=140][b]Limitations[/b][/size]

[list][*]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.
[list][*]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.[/list][/list]

[size=140][b]Future Additions[/b][/size]

If you have a request for more features/endpoints, join the [url=https://discord.gg/wWPp7Hg]AugustinAndroid v2 support server[/url] 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.