NATION

PASSWORD

NationStates API (nationdata/regiondata)

Bug reports, general help, ideas for improvements, and questions about how things are meant to work.

Advertisement

Remove ads

User avatar
Flanderlion
Ambassador
 
Posts: 1618
Founded: Nov 25, 2013
Iron Fist Consumerists

Postby Flanderlion » Wed Jan 15, 2020 10:19 am

Trotterdam wrote:
Agadar wrote:The latter is definitely not allowed.
Says where? There is a list of restricted actions that may not be scripted using the HTML site, and creating or editing a dispatch is not among them (since it only affects your own nation and not anything else in the game world).

Editing was fine, creating was not pre rewrite of that. I'd stick with the prior interpretation until an admin says otherwise.
As always, I'm representing myself.

User avatar
Ferranghia
Civil Servant
 
Posts: 7
Founded: Dec 10, 2015
Corrupt Dictatorship

Postby Ferranghia » Thu Jan 16, 2020 12:42 am

Well then, manual posting it is until an API pops up!
Admiral of Ferranghia and master of the puppet government of the_dorvan_protectorate_of_ferranghia
Slowly building the Nationstates API C# Library

User avatar
[violet]
Site Admin
 
Posts: 14630
Founded: Antiquity

Postby [violet] » Thu Jan 16, 2020 7:39 pm

Ferranghia wrote:Are there any plans of making an endpoint to create dispatches via the API, or do I have to go the HTML script way in order to do that?

There is an (undocumented) API Nation Private Command for dispatches, which I have now released for testing.

You can add, edit, and remove dispatches by following the same process as currently exists for gifting Trading Cards; namely, you have to:
  1. Issue a request and stick "&mode=prepare" on the end
  2. Repeat but this time with "&mode=execute&token=TOKEN_GOES_HERE", where TOKEN_GOES_HERE is the value you received back from the server from Step 1.

When creating or editing a dispatch, you have to supply these parameters: title, text, category, subcategory.

When editing or removing a dispatch, you have to supply: dispatchid.

Examples!

Prepare to add a new dispatch:

Code: Select all
curl -H "X-Password: hunter2" -A "UserAgent Example" "https://www.nationstates.net/cgi-bin/api.cgi" --data "nation=testlandia&c=dispatch&dispatch=add&title=Test%20Dispatch&text=Hello%20there.&category=1&subcategory=105&mode=prepare"


Now do it for real, using the supplied token:

Code: Select all
curl -H "X-Pin: PIN_GOES_HERE" -A "UserAgent Example" "https://www.nationstates.net/cgi-bin/api.cgi" --data "nation=testlandia&c=dispatch&dispatch=add&title=Test%20Dispatch&text=Hello%20there.&category=1&subcategory=105&mode=execute&token=TOKEN_GOES_HERE"


Edit that dispatch:

Code: Select all
curl -H "X-Pin: PIN_GOES_HERE" -A "UserAgent Example" "https://www.nationstates.net/cgi-bin/api.cgi" --data "nation=testlandia&c=dispatch&dispatchid=DISPATCH_ID_GOES_HERE&dispatch=edit&title=Test%20Dispatch%20Edited&text=I%20Was%20Edited.&category=1&subcategory=105&mode=prepare"

curl -H "X-Pin: PIN_GOES_HERE" -A "UserAgent Example" "https://www.nationstates.net/cgi-bin/api.cgi" --data "nation=testlandia&c=dispatch&dispatchid=DISPATCH_ID_GOES_HERE&dispatch=edit&title=Test%20Dispatch%20Edited&text=I%20Was%20Edited.&category=1&subcategory=105&mode=execute&token=TOKEN_GOES_HERE"


Remove that dispatch:

Code: Select all
curl -H "X-Pin: PIN_GOES_HERE" -A "UserAgent Example" "https://www.nationstates.net/cgi-bin/api.cgi" --data "nation=testlandia&c=dispatch&dispatch=remove&dispatchid=DISPATCH_ID_GOES_HERE&mode=prepare"

curl -H "X-Pin: PIN_GOES_HERE" -A "UserAgent Example" "https://www.nationstates.net/cgi-bin/api.cgi" --data "nation=testlandia&c=dispatch&dispatch=remove&dispatchid=DISPATCH_ID_GOES_HERE&mode=execute&token=TOKEN_GOES_HERE"


Please test and let me know how you go!
Last edited by [violet] on Sun Jan 19, 2020 5:46 pm, edited 1 time in total.

User avatar
[violet]
Site Admin
 
Posts: 14630
Founded: Antiquity

Postby [violet] » Thu Jan 16, 2020 8:20 pm

[violet] wrote:Gifting cards is now supported via API! Documentation is under Nation Private Commands.

Please note a change in the function of this Private Command: Previously, a successful "prepare" would return a token wrapped in <TOKEN> tags, like this:

Code: Select all
<NATION id="testlandia">
<SUCCESS><TOKEN>1p1ELXkPJ5tq14GA8vduNwNFDEpAA2UxA8A03OavAOo<TOKEN></SUCCESS>
</NATION>

... but now it doesn't, so it looks like this:
Code: Select all
<NATION id="testlandia">
<SUCCESS>1p1ELXkPJ5tq14GA8vduNwNFDEpAA2UxA8A03OavAOo</SUCCESS>
</NATION>


Generally the API doesn't do breaking changes like this, but the Trading Cards API is still in public beta, and can change without warning.

User avatar
Ferranghia
Civil Servant
 
Posts: 7
Founded: Dec 10, 2015
Corrupt Dictatorship

Postby Ferranghia » Fri Jan 17, 2020 12:56 am

[violet] wrote:
Ferranghia wrote:Are there any plans of making an endpoint to create dispatches via the API, or do I have to go the HTML script way in order to do that?

There is an (undocumented) API Nation Private Command for dispatches, which I have now released for testing.

Please test and let me know how you go!

Woohoo! I'll let you know as soon as I can
Admiral of Ferranghia and master of the puppet government of the_dorvan_protectorate_of_ferranghia
Slowly building the Nationstates API C# Library

User avatar
9003
Chargé d'Affaires
 
Posts: 402
Founded: Oct 25, 2012
Inoffensive Centrist Democracy

Postby 9003 » Fri Jan 17, 2020 9:10 am

Any word yet on setting up the API to do
https://www.nationstates.net/cgi-bin/ap ... a;season=1
rather then searching by card ID?

if it seems to be presenting challenges that's okay too I just didn't want to have it get forgotten about if its an easy implantation
proud member of PETZ people for the Ethical Treatment of Zombies

Active member of The cards market place discord

User avatar
Trotterdam
Powerbroker
 
Posts: 8881
Founded: Jan 12, 2012
Left-Leaning College State

Postby Trotterdam » Fri Jan 17, 2020 11:27 am

9003 wrote:Any word yet on setting up the API to do
https://www.nationstates.net/cgi-bin/ap ... a;season=1
rather then searching by card ID?

if it seems to be presenting challenges that's okay too I just didn't want to have it get forgotten about if its an easy implantation
This was answered here:
[violet] wrote:
Darcania wrote:Loving the card API so far, thank you for implementing it and letting devs play around with the beta.
Probably the most major request from me would be to be able to ask for a card by a specified nation name rather than card ID. For instance, rather than querying for "?q=card+info;cardid=1;season=1", I'd like it if there were an option to query via "?q=card+info;cardname=testlandia;season=1" or similar.
Unfortunately this isn't possible to add without slowing down the Cards API, since it would require loading a nation.

User avatar
August
Spokesperson
 
Posts: 140
Founded: Oct 07, 2011
Anarchy

Postby August » Fri Jan 17, 2020 12:56 pm

[violet] wrote:-dispatch snip-
This is great--I imagine a lot of people have been waiting for this, so thank you for implementing it! However, the whole problem I had with automatically publishing dispatches via the HTML site was that I could only do so with GET requests, which were limited to something like 6000 characters. (I know POST requests should be used to send larger payloads, but those gave me security checks no matter what I tried). Publishing dispatches via the API is giving me the same problem: low character limits, and 414 URI Too Long errors if I go over. Is there any way this limit could be removed, or is this endpoint intended just for short dispatches? Disregard. Finally got it to work.

As a minor note, the code block for edits is missing this snippet.
Code: Select all
&dispatchid=DISPATCH_ID_GOES_HERE
Last edited by August on Fri Jan 17, 2020 6:40 pm, edited 1 time in total.
|| AA Founder - Retired.

My Projects: AugustinAndroid (Server) | Augustin Alliance (Server) | NS Leaders (Server) | Tech suggestions | About me
I heard it was you / talkin' 'bout a world where all is free / it just couldn't be / and only a fool would say that...

User avatar
Trotterdam
Powerbroker
 
Posts: 8881
Founded: Jan 12, 2012
Left-Leaning College State

Postby Trotterdam » Fri Jan 17, 2020 5:35 pm

You can use POST requests on the API? I do.

User avatar
August
Spokesperson
 
Posts: 140
Founded: Oct 07, 2011
Anarchy

Postby August » Fri Jan 17, 2020 6:39 pm

Trotterdam wrote:You can use POST requests on the API? I do.
I tried it earlier and it failed, and as mentioned before, it failed many times while interacting with the HTML site. Naturally, I just tried it again and it worked for the first time ever, so thank you for prompting me to give it one more shot.
|| AA Founder - Retired.

My Projects: AugustinAndroid (Server) | Augustin Alliance (Server) | NS Leaders (Server) | Tech suggestions | About me
I heard it was you / talkin' 'bout a world where all is free / it just couldn't be / and only a fool would say that...

User avatar
Ferranghia
Civil Servant
 
Posts: 7
Founded: Dec 10, 2015
Corrupt Dictatorship

Postby Ferranghia » Sat Jan 18, 2020 11:24 am

August wrote:
Trotterdam wrote:You can use POST requests on the API? I do.
I tried it earlier and it failed, and as mentioned before, it failed many times while interacting with the HTML site. Naturally, I just tried it again and it worked for the first time ever, so thank you for prompting me to give it one more shot.


I figured out my POSTs were being turned into GETs by C#'s http client because I was posting all my requests to https://nationstates... instead of https://www.nationstates, my requests were then being redirected and for some reason the client dropped the post.

All's good now.
Admiral of Ferranghia and master of the puppet government of the_dorvan_protectorate_of_ferranghia
Slowly building the Nationstates API C# Library

User avatar
[violet]
Site Admin
 
Posts: 14630
Founded: Antiquity

Postby [violet] » Sat Jan 18, 2020 10:48 pm

Trotterdam wrote:You can use POST requests on the API? I do.

Do you ever!

Gloomhaven is by far our most prolific bot.

User avatar
[violet]
Site Admin
 
Posts: 14630
Founded: Antiquity

Postby [violet] » Sun Jan 19, 2020 5:47 pm

Updated API doc to cover Nation Private Command "dispatch".

User avatar
Minoa
Senator
 
Posts: 4694
Founded: Oct 05, 2011
Civil Rights Lovefest

Postby Minoa » Sat Feb 01, 2020 10:02 am

Hello, is there a API shard for determining whether a nation is on vacation mode or not? This could benefit those who wish to improve the efficiency of the pings (to prevent the nation from ceasing to exist due to inactivity), and also benefit those who see vacation mode indicators as a way to improve the efficiency of telegrams. [EDIT: that was stupid, Minoa] For me, it would tell me which nations are not in vacation mode, so I can change them to use vacation mode.
Last edited by Minoa on Sun Feb 02, 2020 1:31 am, edited 2 times in total.
Mme A. d'Oiseau, B.A. (State of Minoa)

User avatar
Trotterdam
Powerbroker
 
Posts: 8881
Founded: Jan 12, 2012
Left-Leaning College State

Postby Trotterdam » Sat Feb 01, 2020 11:02 am

Telling whether a nation that isn't yours is in vacation mode is something you can't do on the normal site, so I don't see why you should be able to do it in the API.

User avatar
Minoa
Senator
 
Posts: 4694
Founded: Oct 05, 2011
Civil Rights Lovefest

Postby Minoa » Sun Feb 02, 2020 1:26 am

Trotterdam wrote:Telling whether a nation that isn't yours is in vacation mode is something you can't do on the normal site, so I don't see why you should be able to do it in the API.

I am sorry if I slipped up there.

Maybe I should revise my idea to be a private shard where users can check if one of their nations is in vacation mode or not.
Last edited by Minoa on Sun Feb 02, 2020 1:29 am, edited 1 time in total.
Mme A. d'Oiseau, B.A. (State of Minoa)

User avatar
The World Capitalist Confederation
Postmaster-General
 
Posts: 12839
Founded: Dec 07, 2018
Capitalist Paradise

Postby The World Capitalist Confederation » Tue Feb 04, 2020 3:50 pm

How do I make an api to send out campaign telegrams to 8 people at a time from a selected list?

What I'm trying to do is have a list of every delegate sorted by region size, and then have the api send out the same campaign telegram to 8 of them at a time.

I'm surprised that these stamp-free campaign tools don't exist already, as, whilst slow, they are free and would offer some level of equity to the WA campaigning field.
Please Watch
“We could manage to survive without the money changers and stockbrokers, but we would rather find it difficult to survive without miners, steel workers and those who cultivate the land.” - Nye Bevan, Minister of Health under Clement Attlee

“The mutual-aid tendency in man has so remote an origin, and is so deeply interwoven with all the past evolution of the human race, that is has been maintained by mankind up to the present time, notwithstanding all vicissitudes of history.” - Peter Krotopkin, evolutionary biologist and political writer.

User avatar
Frisbeeteria
Senior Game Moderator
 
Posts: 24770
Founded: Dec 16, 2003
Anarchy

Postby Frisbeeteria » Tue Feb 04, 2020 4:14 pm

The World Capitalist Confederation wrote:How do I make an api to send out campaign telegrams to 8 people at a time from a selected list?

You don't. API telegrams go out one at a time and have a throttle. Manual telegrams may be sent to 8 recipients at once with no throttle. Stamped telegrams can be sent to thousands of recipients at once with no throttle.

The World Capitalist Confederation wrote:I'm surprised that these stamp-free campaign tools don't exist already, as, whilst slow,

They do, and the speed choice is deliberate. You can work hard manually, pay for stamps, or accept the limits of the API to do set-it-and-forget-it campaigning. We have no intention of making free mass mailing (aka spamming) any easier.

User avatar
The World Capitalist Confederation
Postmaster-General
 
Posts: 12839
Founded: Dec 07, 2018
Capitalist Paradise

Postby The World Capitalist Confederation » Tue Feb 04, 2020 4:48 pm

Frisbeeteria wrote:
The World Capitalist Confederation wrote:How do I make an api to send out campaign telegrams to 8 people at a time from a selected list?

You don't. API telegrams go out one at a time and have a throttle. Manual telegrams may be sent to 8 recipients at once with no throttle. Stamped telegrams can be sent to thousands of recipients at once with no throttle.

The World Capitalist Confederation wrote:I'm surprised that these stamp-free campaign tools don't exist already, as, whilst slow,

They do, and the speed choice is deliberate. You can work hard manually, pay for stamps, or accept the limits of the API to do set-it-and-forget-it campaigning. We have no intention of making free mass mailing (aka spamming) any easier.

I'm willing to take the limits of the API. How do I get the API to start sending my campaign telegram template?
Please Watch
“We could manage to survive without the money changers and stockbrokers, but we would rather find it difficult to survive without miners, steel workers and those who cultivate the land.” - Nye Bevan, Minister of Health under Clement Attlee

“The mutual-aid tendency in man has so remote an origin, and is so deeply interwoven with all the past evolution of the human race, that is has been maintained by mankind up to the present time, notwithstanding all vicissitudes of history.” - Peter Krotopkin, evolutionary biologist and political writer.

User avatar
Frisbeeteria
Senior Game Moderator
 
Posts: 24770
Founded: Dec 16, 2003
Anarchy

Postby Frisbeeteria » Tue Feb 04, 2020 7:47 pm

The World Capitalist Confederation wrote:How do I get the API to start sending my campaign telegram template?

Uhh, that's not how it works. You need a script. Look at the first post in this thread, and maybe at some of the other posts in Technical for suggestions.

User avatar
The Northern Light
Spokesperson
 
Posts: 138
Founded: Oct 10, 2014
Inoffensive Centrist Democracy

Postby The Northern Light » Tue Feb 04, 2020 8:40 pm

[violet] wrote:Updated API doc to cover Nation Private Command "dispatch".

Thank you very much for implementing this! I finally got a chance to port all of my dispatch maintenance script to the API and it works great :) .

---------

I had a couple of questions:

1) Do the "mode=prepare" and "mode=execute" count as two separate API requests as far as rate limit is concerned?

2) Is it necessary to provide the full dispatch title and text for the "mode=prepare", or can we have placeholders for those and only provide the final version for "mode=execute"? I am asking because the dispatch text can be very large in size, and sending it over twice when it is only being used once seems like a huge waste of bandwidth for both the NS server and the person making the API request.

---------

I also had a suggestion: Would it be possible to remove the "category" part of the request? It seems redundant, given that we already specify a "subcategory", and the "category" is nothing else but the first digit of the "subcategory".

I imagine the reason why we have to specify both is that the gameside POST request for editing dispatches requires both. So, if that's hard to change, that's understandable, but I thought I should bring up this small suggestion anyway.
Home of the WADP, Planet Eras, and the Constibillocode!
Join The North Pacific!
Where the democracy is strong, the debate robust, and the rum plentiful!

Forum | Discord Chat | Citizenship | Executive Staff | North Pacific Army | World Assembly Ministry | Roleplay | Trading Cards | Handbook

User avatar
The Northern Light
Spokesperson
 
Posts: 138
Founded: Oct 10, 2014
Inoffensive Centrist Democracy

Postby The Northern Light » Wed Feb 05, 2020 6:13 pm

Request 1

Would it be possible to have all private API requests that successfully authenticate return the currently valid pin, regardless of how authentication was done (password, autologin, or pin)?

Short explanation: It makes management of private API login sessions across multiple scripts that run in random order easier.

Long explanation: After a fair amount of experimentation, I've concluded that the most robust way to handle API authentications when multiple scripts are accessing the same nation in random order is to implement a makeshift "cookie" system.

Here is how I thought this would work: Let's say that "cookie.txt" is a pre-specified file somewhere in the system that all scripts can access. Using this file, I make sure that every private API call follows the same pattern shown below (I'll use a mix of curl and pseudocode for demonstration, and I skip the use of "autologin" just to keep the example simple):
Code: Select all
your_pin = readPinFromCookie("cookie.txt")

curl -A "${your_user_agent}" -H "X-pin: ${your_pin}" -H "X-password: ${your_password}" -D "cookie.txt" "https://www.nationstates.net/cgi-bin/api.cgi?nation=${your_nation}&q=ping"

This way, before I make any private call, I'd check the "cookie" for the latest available pin. Then, I'd make a private API call providing both the pin and password. If the pin is still valid, the request will go through. If it's not, authentication will work through the password. In both cases, the returned headers will be written in the "cookie", to be used by future requests.

Unfortunately, the above does not work. The reason is that, when authentication with pin is successful, the returned headers do not include the X-pin header. Therefore, the updated cookie will no longer have the pin, and future private requests will end up always falling back to the password. In turn, this means that, when many calls in quick succession are made, half of them will run into 409 conflicts.

This problem can be circumvented by modifying the above call pattern as follows:
Code: Select all
your_pin = readFirstPinFromCookie("cookie.txt")

curl -A "${your_user_agent}" -H "X-pin: ${your_pin}" -H "X-password: ${your_password}" -D "cookie.txt" "https://www.nationstates.net/cgi-bin/api.cgi?nation=${your_nation}&q=ping"

appendLatestPinToCookie("cookie.txt", "${your_pin}")

This solution works, and I've already adjusted all of my code to use it. But it just seems unnecessarily complicated, and prone to result in bugs and confusion. Changing the private API responses so that the returned headers always include the currently valid pin, regardless of how authentication was performed, will help streamline the above pipeline, by making it possible to use the simpler first version.



Request 2

Would it be possible to make private API requests compatible with cookies, including cookies from gameside sessions? By "compatible" I mean that: 1) the authentication information from a successful private API call can be returned through a cookie instead of headers; and 2) a cookie available from a previous gameside session or successful private API call can be used for authentication on a subsequent private API call.

Explanation: This request is for three reasons. The first reason is that it makes the pipeline I described above even simpler (and, arguably, closer to standard practice for persistent sessions, which tend to rely on cookies rather than header info). I can make all private API calls follow a pattern like:
Code: Select all
curl -A "${your_user_agent}" -H "X-password: ${your_password}" -b "cookie.txt" -c "cookie.txt" "https://www.nationstates.net/cgi-bin/api.cgi?nation=${your_nation}&q=ping"

There's no longer need for manual processing of returned headers.

The second reason is that it'd help reduce conflicts between gameside sessions and private API sessions. To give an example: I often find myself setting a script to perform several automated tasks on my nation through the private API (backup notifications, update a whole bunch of dispatches, send a round of card gifts, etc.). These tasks can run for several minutes.

If during that time I forget that the script is running and log into my nation, I end up making many of the private API calls fail to authenticate. Sometimes I don't even need to intentionally do a new gameside login; if I so much as have the nation page open on a tab, and I navigate to that tab, I can end up interrupting the API script that is running at the same time. Allowing the private API calls to interface with the cookies used by the gameside would help greatly reduce this type of issues.




None of the above two requests are absolutely critical as far as I am concerned, as at this point my codebase works robustly enough without them. But I think they would be quality-of-life improvements for both myself, and potentially other users having similar use cases. Especially request 1 should be straightforward.

Thanks for the consideration!
Home of the WADP, Planet Eras, and the Constibillocode!
Join The North Pacific!
Where the democracy is strong, the debate robust, and the rum plentiful!

Forum | Discord Chat | Citizenship | Executive Staff | North Pacific Army | World Assembly Ministry | Roleplay | Trading Cards | Handbook

User avatar
SherpDaWerp
Diplomat
 
Posts: 857
Founded: Mar 02, 2016
Civil Rights Lovefest

Postby SherpDaWerp » Thu Feb 13, 2020 12:06 am

Bit of an odd question, this one:

What order, if any, does the server return nations when you query:
https://www.nationstates.net/cgi-bin/ap ... &q=nations

It's quite obviously not alphabetical and doesn't seem to be based on any of the census scores, but it doesn't change, so it's not random either. I assume it's something to do with the order the server processes them in? Clarification pls

User avatar
Phydios
Minister
 
Posts: 2318
Founded: Dec 06, 2014
Inoffensive Centrist Democracy

Postby Phydios » Thu Feb 13, 2020 6:52 am

SherpDaWerp wrote:Bit of an odd question, this one:

What order, if any, does the server return nations when you query:
https://www.nationstates.net/cgi-bin/ap ... &q=nations

It's quite obviously not alphabetical and doesn't seem to be based on any of the census scores, but it doesn't change, so it's not random either. I assume it's something to do with the order the server processes them in? Clarification pls

It's not Nation ID either...odd. I expected that to be the answer.
Romans 1:18-2:29, Ephesians 2:1-10
But God’s angry displeasure erupts as acts of human mistrust and wrongdoing and lying accumulate, as people try to put a shroud over truth. But the basic reality of God is plain enough. Open your eyes and there it is! | Those people are on a dark spiral downward. But if you think that leaves you on the high ground where you can point your finger at others, think again. Every time you criticize someone, you condemn yourself. | It’s a wonder God didn’t lose His temper and do away with the whole lot of us. Instead, immense in mercy and with an incredible love, He embraced us. He took our sin-dead lives and made us alive in Christ. He did all this on His own, with no help from us!

User avatar
9003
Chargé d'Affaires
 
Posts: 402
Founded: Oct 25, 2012
Inoffensive Centrist Democracy

Postby 9003 » Thu Feb 13, 2020 11:34 am

SherpDaWerp wrote:Bit of an odd question, this one:

What order, if any, does the server return nations when you query:
https://www.nationstates.net/cgi-bin/ap ... &q=nations

It's quite obviously not alphabetical and doesn't seem to be based on any of the census scores, but it doesn't change, so it's not random either. I assume it's something to do with the order the server processes them in? Clarification pls



It appears to be based on residency with the most stationary at the start and as nations move in they are simply appended to the end.
proud member of PETZ people for the Ethical Treatment of Zombies

Active member of The cards market place discord

PreviousNext

Advertisement

Remove ads

Return to Technical

Who is online

Users browsing this forum: Gandoor, Phydios, Venicea

Advertisement

Remove ads