NationStates API (nationdata/regiondata)

[Bluelight-R006]

Well, I got the client key, tag and the TGID. I made my template and I filled up the client key, tag and the TGID in the link. They told me to send my telegrams to that link. I don’t get it by sending telegrams to that link because there’s nothing there — when I opened it, it said client isn’t authorised or something.

Can someone help and explain what’s happening?

[Frisbeeteria]

The API is a method by which your script can send telegrams. It is not a telegram sending script. It's just a portal, the front door if you will. If you don't have a telegram script of some sort, the API is useless to you.

Look around this thread and this forum. Several people offer public scripts.

[Bluelight-R006]

The API is a method by which your script can send telegrams. It is not a telegram sending script. It's just a portal, the front door if you will. If you don't have a telegram script of some sort, the API is useless to you.

Look around this thread and this forum. Several people offer public scripts.

Ah. Got it. Needed to clarify this. Thanks.

[The Greater Low Countries]

So I own one nation in my region, and another one in another region. I have a few questions about how I am allowed to send API telegrams with multiple nations.

• Can I share a client key between two nations?
• Can I own two client keys?
• Can I use API telegramming on as many nations as I want?

[Frisbeeteria]

1. Can I share a client key between two nations?
2. Can I own two client keys?
3. Can I use API telegramming on as many nations as I want?

1. Client keys are region specific, so you'll only be able to use it to recruit for the region that applied for it. Can two people from the same region use a single key to recruit? Yes, but there is no benefit if they both run simultaneously. The API rate limit will still apply. The net impact is that one of the recruiters will send most or all of their telegrams, and the other will have most or all of his bounce. We'd greatly prefer than you not do this, as even bouncing the message uses resources unnecessarily.
   If they take turns, then yes, it can be shared effectively.
2. Yes. You can own different keys for different regions. The nation applying needs to be a resident of the region in question, so it makes sense to have a resident puppet hold the key. As the player, you can have more than one key.
3. Depends on how your script works. If it's a browser-based script, then the session_ID will kick off all but the latest nation. I honestly don't know whether their are other methods that allow simultaneous scripting on a single computer. Different nations on different computers can certainly run simultaneously.

[The Greater Low Countries]

1. Can I share a client key between two nations?
2. Can I own two client keys?
3. Can I use API telegramming on as many nations as I want?

1. Client keys are region specific, so you'll only be able to use it to recruit for the region that applied for it. Can two people from the same region use a single key to recruit? Yes, but there is no benefit if they both run simultaneously. The API rate limit will still apply. The net impact is that one of the recruiters will send most or all of their telegrams, and the other will have most or all of his bounce. We'd greatly prefer than you not do this, as even bouncing the message uses resources unnecessarily.
   If they take turns, then yes, it can be shared effectively.
2. Yes. You can own different keys for different regions. The nation applying needs to be a resident of the region in question, so it makes sense to have a resident puppet hold the key. As the player, you can have more than one key.
3. Depends on how your script works. If it's a browser-based script, then the session_ID will kick off all but the latest nation. I honestly don't know whether their are other methods that allow simultaneous scripting on a single computer. Different nations on different computers can certainly run simultaneously.

Thanks for the help, really appreciate it!

[Aibohphobia]

I find it difficult to understand what exactly the following shards return/mean and would appreciate an explanation:

• admirable
• gavote
• income
• rcensus

What is the difference between custom and non-custom tags, such as customleader and leader? Demonym and demonym2?

Thank you in advance.

[Trotterdam]

admirable

On your main nation page, you will see text that goes along the lines of:

The Recursiveness of Aibohphobia is a gargantuan, efficient nation, ruled by Dark Inquisitor with an iron fist, and renowned for its avowedly heterosexual populace, irreverence towards religion, and devotion to social welfare. The hard-nosed, cynical, humorless population of 16.162 billion Aibohphobians are ruled without fear or favor by a psychotic dictator, who outlaws just about everything and refers to the populace as "my little playthings."

The part that I underlined is what the "admirable" shard returns.

Note that there are generally several different adjectives that your nation nation qualifies for, of which one is randomly selected for display every time you load the page, either on the normal site or the API. Unforunately there is not currently any way to obtain a list of all values that your nation qualifies for, short of repeating the API check a bazillion times, sifting out duplicates, and hoping you got 'em all.

gavote

That clearly stands for "General Assembly vote". Unfortunately, there is no resolution currently at vote, so I can't easily test how it works. In any case, it should only ever return something interesting for nations that are in the World Assembly.

income

Average income as displayed on your nation page. The same value represented by census score 72, but actually with less accuracy, making it fairly redundant.

rcensus

Appears to give the same value as q=census&mode=rrank. Similarly, wcensus gives the same value as q=census&mode=rank. Not sure why these exist, probably a holdover from an earlier version of the API that is now obsolete but kept for the benefit of older scripts that haven't been updated to use the new features.

What is the difference between custom and non-custom tags, such as customleader and leader?

The only difference is if the nation hasn't entered a custom field. Either due to not having unlocked it yet, or due to deliberately leaving it blank. In that case, "customleader" etc. will return a blank (to represent the lack of a custom entry), while "leader" etc. will return the default values used for the issue macros ("@@NAME@@ City", "Leader", "a major religion").

Demonym and demonym2?

"demonym" is the adjective demonym ("Spanish", etc.), while "demonym2" is the noun demonym ("Spaniard", etc.), as distinguished on your settings page. On very many nations they will be identical, but they don't have to be,

[Aibohphobia]

Not sure why these exist, probably a holdover from an earlier version of the API that is now obsolete but kept for the benefit of older scripts that haven't been updated to use the new features.

First of all, thank you very much!
I do not see why those redundant values would be kept, as the API allows one to select its version number as part of the request ('v='). Perhaps, an oversight?

The only difference is if the nation hasn't entered a custom field. Either due to not having unlocked it yet, or due to deliberately leaving it blank. In that case, "customleader" etc. will return a blank (to represent the lack of a custom entry), while "leader" etc. will return the default values used for the issue macros ("@@NAME@@ City", "Leader", "a major religion").

Seems kind of pointless. I appreciate the detailed explanation.

"demonym" is the adjective demonym ("Spanish", etc.), while "demonym2" is the noun demonym ("Spaniard", etc.), as distinguished on your settings page. On very many nations they will be identical, but they don't have to be.

Thank you once more for helping me and another fellow from my region - SherpDaWerp.

P.S. The issue command seems completely dysfunctional. I've tried both GET and POST requests through cURL, and they do nothing. The URL's are properly formed, and XML is parsed without errors as well. I'll check omitting 'v=' from the query tomorrow as well as what response the server actually returns.

[Trotterdam]

The only difference is if the nation hasn't entered a custom field. Either due to not having unlocked it yet, or due to deliberately leaving it blank. In that case, "customleader" etc. will return a blank (to represent the lack of a custom entry), while "leader" etc. will return the default values used for the issue macros ("@@NAME@@ City", "Leader", "a major religion").

Seems kind of pointless. I appreciate the detailed explanation.

Eh, I appreciate it. For my use case, it's more useful to know the macros as they actually appear in issues without needing to substitute blanks with default values myself, but I can see how other people might be interested in the difference between a nation that, say, hasn't named custom capital city versus one whose capital city name just happens to match the default (since several real-life nations actually do have capital cities of the "@@NAME@@ City" format). Note that the difference is visible on your nation page.

P.S. The issue command seems completely dysfunctional. I've tried both GET and POST requests through cURL, and they do nothing. The URL's are properly formed, and XML is parsed without errors as well. I'll check omitting 'v=' from the query tomorrow as well as what response the server actually returns.

I tried it once a few days back and it worked for me, though I was using Wget, not cURL. (I don't use either one for my actual scripting these days, but this was just a single test request, not a script.)

[The Northern Light]

Also, would it be possible to have an API query which tells us what kind of telegram is being sent? Something like:

Code: Select all

https://www.nationstates.net/cgi-bin/api.cgi?a=infoTG&tgid=(TGID)&key=(Secret Key)

Returning information on the telegram itself, like the delivery data, by whom the telegram was blocked, and what kind of telegram is being sent (recruitment, campaign, unmarked).

Bump.

Yes that's a good idea, but it's lower in my priorities than, say, improving update speed right now. Sorry.

Would it be possible to revisit this request? It'd be very helpful for preventing all sorts of TG API misuse (accidental or otherwise).

[Aibohphobia]

I tried it once a few days back and it worked for me, though I was using Wget, not cURL. (I don't use either one for my actual scripting these days, but this was just a single test request, not a script.)

My bot is a cron job that runs a PHP script. What do you normally use instead of cURL and wget?

[Trotterdam]

What do you normally use instead of cURL and wget?

This, actually.

It kinda happened by accident, really. I was using Qt anyway for designing my GUI. I was looking around for a separate library to handle HTTP requests, then I noticed Qt already had one built-in and so figured I might as well use that.

I wouldn't recommend it unless you're already using Qt and C++, which you're clearly not.

Some of my really old scripts (on my previous ancient three-quarters-dead computer) did use wget, but I don't use most of them anymore. There's one that I crudely upgraded to run on my new computer, but it only makes a few requests per day in response to manual user action.

[Aibohphobia]

What do you normally use instead of cURL and wget?

This, actually.

[...]

I wouldn't recommend it unless you're already using Qt and C++, which you're clearly not.

[...]

Thank you! That's really cool. Have you developed NS tools just for yourself or more "global" ones too?

I do program in C++, but I am not familiar with Qt development indeed. Not sure where the "clearly" came from. Does being a web-developer automatically put one on a lower tier somehow?

I've managed to make it run after all. It just needed an X-Pin refresh, for some reason.

[Trotterdam]

Thank you! That's really cool. Have you developed tools just for yourself or more "global" ones too?

To date I have not shared any of my tools, although I am of course sharing the results produced by my tools.

I'd be entirely willing to share my API wrapper if anyone has any use for it, but like I said, it's designed for a fairly specific programming environment that isn't all that common in the NS scripting community. This API wrapper does not currently support private shard/command authentification (as I do not use these features currently), but I could fairly easily add these.

Not sure where the "clearly" came from.

To clarify: It's not clear that you have never worked with Qt. It is clear that you're not using it for your current application, since you explicitly said you're coding it in PHP.

I've managed to make it run after all. It just needed an X-Pin refresh, for some reason.

Congratulations!

I'm not sure how that works, though. From what I understand of the API documentation, if the X-Pin doesn't work, the server should automatically ignore it and use your X-Password instead. You should supply an X-Password regardless, because X-Pins expire constantly (every time you log into your nation normally, for example).

If you got it to work, you should compare notes with SherpDaWerp, who is also using PHP/cURL and seems to still be having problems.

[Flanderlion]

I've managed to make it run after all. It just needed an X-Pin refresh, for some reason.

Congratulations!

I'm not sure how that works, though. From what I understand of the API documentation, if the X-Pin doesn't work, the server should automatically ignore it and use your X-Password instead. You should supply an X-Password regardless, because X-Pins expire constantly (every time you log into your nation normally, for example).

You need the X-Pin though, as otherwise you get too many requests type errors after the first request or so.

[Trotterdam]

You need the X-Pin though, as otherwise you get too many requests type errors after the first request or so.

Yes, I know that.

On your first request you supply only an X-Password, and memorize the X-Pin that you get in response. On subsequent requests you supply both, and continue rememorizing the X-Pins that you get in response in case it changed.

You most definitely do not hard-code any particular X-Pin into your script.

[Aibohphobia]

I'd be entirely willing to share my API wrapper if anyone has any use for it, but like I said, it's designed for a fairly specific programming environment that isn't all that common in the NS scripting community.

Got it, thank you very much for clarifying. I was just curious. I like learning, and it would be nice to see how a knowledgeable person approaches a similar problem.

I'm not sure how that works, though. From what I understand of the API documentation, if the X-Pin doesn't work, the server should automatically ignore it and use your X-Password instead. You should supply an X-Password regardless, because X-Pins expire constantly (every time you log into your nation normally, for example).

The API isn't phrased perfectly, I concur. For example, it doesn't explicitly say that X-Pin and X-Autologin are returned only if you access a private shard (yes, even when X-Password is provided as one of the headers for the request). Certain shards (such as the ones I initially inquired about) lack proper documentation (at least in the form of something like on-hover tooltips).

If you got it to work, you should compare notes with SherpDaWerp, who is also using PHP/cURL and seems to still be having problems.

It's very kind of you to remember. I sent him a telegram with a link to my source code as soon as I had got it done. To be honest, I don't really understand why he didn't address me in the first place, because we are from the same region, talk reasonably often, and he requested the source code for the previous version of my bot. I think I even shared my remastered version of Wolfram and Hart's script with him at some stage, but I might be wrong. He knows I work with PHP and JavaScript.

You need the X-Pin though, as otherwise you get too many requests type errors after the first request or so.

Yes, I know that.

On your first request you supply only an X-Password, and memorize the X-Pin that you get in response. On subsequent requests you supply both, and continue rememorizing the X-Pins that you get in response in case it changed.

You most definitely do not hard-code any particular X-Pin into your script.

I disagree. The previous version of my bot did not work through the API, and I was simply scraping raw HTML through cURL (I come from an age where API's did not exist, I feel more comfortable with doing that, and I didn't realise responding to issues without using the API would get banned at any stage, because a moderator gave me "the green light" for a script that didn't affect other nations or the region's activity log). My script survived on the same '__cfduid=get-your-own; pin=tasty; autologin=cookie;' cookie for almost 3 years, excluding a short period where my server's IP address was banned by the site. Naturally, I logged into the nation manually every now and then. I highly doubt it's any different through the API, but I'll see soon enough. If it's different, I'm in for more code rewriting tomorrow.

[Trotterdam]

I didn't realise responding to issues without using the API would get banned at any stage

It's a fairly recent rule, introduced mostly for the sake of the card minigame. If you've been doing it for 3 years, it was legal for most of that time. The rule change was not well-advertised if you're not following the Technical forum.

My script survived on the same '__cfduid=get-your-own; pin=tasty; autologin=cookie;' cookie for almost 3 years,

That would be it. As explained in the documentation, an autologin serves essentially the same purpose as a password, behaving closer to a password than a PIN. You still need to supply either a password or an autologin, the PIN by itself won't do.

I'm not sure what the benefit of using X-Autologin is. The documentation says it lets you avoid having to store your password anywhere, but wouldn't someone else who learned your autologin code be able to steal your nation just as well as someone who learned your password?

[Aibohphobia]

It's a fairly recent rule, introduced mostly for the sake of the card minigame. If you've been doing it for 3 years, it was legal for most of that time. The rule change was not well-advertised if you're not following the Technical forum.

As you can probably see from my stats, I rarely post, and I think all of my posts are in Technical and "Help Us Fix Old Issues". There is mixed information about this change, and I was lucky enough to get warned by a kind soul about it.

You still need to supply either a password or an autologin, the PIN by itself won't do.

I'm not sure what the benefit of using X-Autologin is. The documentation says it lets you avoid having to store your password anywhere, but wouldn't someone else who learned your autologin code be able to steal your nation just as well as someone who learned your password?

It's actually worse. I got this issue before (when I mentioned having to update the bot's X-Pin). If you log in your nation manually (even without checking "Remember me"), it somehow screws the API commands (they result in 409's afterwards)! I am referencing a private shard and trying to run commands on my end. The shard works fine with the old X-Pin, but API commands result in this:

Previous Login Too Recent

You attempted to log in with a nation that already logged in successfully a few seconds earlier. This may mean that you are attempting to maintain a connection via password or autologin rather than supplying a PIN.

Error: 409 Conflict

I am assuming, this is a block on commands only, because scraping raw HTML never resulted in that problem. So one needs to run a check on the response from the server for API commands functionality. And, unlike what the API documentation says (or some forum post - I don't remember), "waiting for about 6 seconds" doesn't resolve the issue. The server responds with 409 until the X-Pin is renewed.

As for the second part of your post, X-Autologin doesn't work without an X-Pin, as far as I know. I think so because when I was using session cookies for the first version of my script, I tried different value pairs, and X-Autologin didn't work by itself. In fact, the X-Autologin cookie variable only gets populated for a nation you choose the "Remember me" option for upon logging in.

Update: The 409 problem is really annoying. It produces invalid HTML to begin with, but one can check for it through a dummy request (like 'nation=testlandia&c=issue' - without supplying 'issue' or 'option') and test it against a regular expression afterwards.

[Trotterdam]

There is mixed information about this change,

The unnamed moderator who posted that is incorrect.

Rules restricting non-API scripts from doing many things have been in place for a long time, but this was not one of them. Previously, the rule was that you could do anything that doesn't cause changes to anything other than your own nation, which answering issues explicitly fell under because it only changes your own nation. That rule is still more-or-less present, but answering issues was added as an additional exception less than a year ago.

Though ultimately, I suppose that when the rule was made doesn't matter much. The important thing is that it's illegal now, and whether or not it was illegal a year ago isn't much help unless you have a time machine.

The server responds with 409 until the X-Pin is renewed.

Yes. That's what the documentation says.

Where are you even getting your X-Pin from, if your script is never managing to connect without it? Are you grabbing it straight from your browser cookies? That's pretty clearly not how it's supposed to work (unless your script is actually running in your browser, I guess - I hadn't actually considered that design). Scripts should be able to work on their own, entirely separate from your browser access to the game.

As for the second part of your post, X-Autologin doesn't work without an X-Pin, as far as I know.

Again, look at the flowchart in the documentation. Autologin is only checked if your PIN is invalid, which will happen all the time, because PINs are being invalidated constantly (anytime you log in elsewhere, anytime you go two hours without doing anything).

Basic program flow code would go like this:
1. Store X-Password on disk.
2. Store X-Password and X-Pin in memory (read former from disk whenever starting the script, initialize latter to blank).
3. For each request, send both X-Password and X-Pin, except the latter is sent only if you actually have one (so not for the first request of the session).
4. If request works, update memorized X-Pin according to the server response, then repeat steps 3-5 as often as necessary to finish everything you want to do.
5. If request fails with a 409 error, wait a while and try again. If request fails with a 403 error, abort and report failure.

More sophisticated program flow code (if you see a point to autologin, which I don't) would go like this:
1. Store X-Autologin on disk (but it's blank the first time you run the script - don't copy it from your browser).
2. Store X-Password, X-Autologin, and X-Pin in memory (X-Autologin is read from disk, others are initialized to blank when starting the script).
3. If you have a valid-looking X-Autologin, then make your request sending both that X-Autologin and, if you also have an X-Pin, that too. If that works, memorize the X-Pin the server returns, and repeat step 3 as often as necessary to finish your script, skipping step 4. If it gives a 403, continue to step 4.
4. If you got a 403 error on step 3, or if you skipped step 3 due to not having an X-Autologin yet, then instead prompt the user to enter a password, then send the request using that X-Password. If that works, memorize both the X-Autologin and X-Pin the server returns, save the former to disk, and repeat step 3 as often as necessary to finish your script. If it gives a 403, complain that the user entered the wrong password.
5. If either step 3 or 4 gives a 409 error, then just wait a few seconds and try again. Really, that works for most errors, just make sure not to ignore a 403.

Update: The 409 problem is really annoying. It produces invalid HTML to begin with, but one can check for it through a dummy request (like 'nation=testlandia&c=issue' - without supplying 'issue' or 'option') and test it against a regular expression afterwards.

I don't get what you mean.

You should only check the XML if your request got a 200 response code. Otherwise, you should just check the HTTP response code and ignore the actual text returned. In PHP/cURL, you appear to do this using curl_getinfo($query, CURLINFO_RESPONSE_CODE), according to the manual.

[Aibohphobia]

I suppose that when the rule was made doesn't matter much. The important thing is that it's illegal now, and whether or not it was illegal a year ago isn't much help unless you have a time machine.

It's important to me in determining whether I am sane and remember things well. After receiving that message from the moderator, I was afraid I had been breaking the rules all that time.

That's what the documentation says.

Where are you even getting your X-Pin from, if your script is never managing to connect without it? Are you grabbing it straight from your browser cookies? That's pretty clearly not how it's supposed to work (unless your script is actually running in your browser, I guess - I hadn't actually considered that design). Scripts should be able to work on their own, entirely separate from your browser access to the game.

What the documentation and the 409 message tell me is that once an X-Pin is set, it doesn't need to get renewed (and it doesn't for private shards, the issue's only present with commands).

I have a separate login.php script that I grab the X-Pin and X-Autologin from by running it manually once. It seemed ridiculous to me (and it still does) to check if the X-Pin is "current" for every bloody API command. It's 1 additional API request that is completely unnecessary given the "rigorous" system we're dealing with. According to the documentation, the whole point of having an X-Pin is so that you don't have to authenticate every time you issue an API command. Otherwise the easiest way for me to send them is by simply using X-Password and ignoring the other custom headers.

What irritates me the most is that the previous login is not recent at all! It was a manual login with "Remember me" unchecked. 12+ hours have passed since then, and the server still returns a 409.

Again, look at the flowchart in the documentation. Autologin is only checked if your PIN is invalid, which will happen all the time, because PINs are being invalidated constantly (anytime you log in elsewhere, anytime you go two hours without doing anything).

None of this is in the documentation. The flowchart is nice, of course, but it doesn't say how to check for X-Pin validity. The documentation should really be more clear on that.

If you have a valid-looking X-Autologin, then make your request sending both that X-Autologin and, if you also have an X-Pin, that too. If that works, memorize the X-Pin the server returns, and repeat step 3 as often as necessary to finish your script

How would you identify a valid X-Autologin? Compare it to an empty string?

save the former to disk

When you say "save to disk", what exactly do you mean? Saving it to a file? What's the advantage of that compared to having the value in plaintext inside the script itself?

prompt the user to enter a password

That doesn't really work for me, as I am running it from my server's crontab. It doesn't receive any user input.

I don't get what you mean.

You should only check the XML if your request got a 200 response code. Otherwise, you should just check the HTTP response code and ignore the actual text returned. In PHP/cURL, you appear to do this using curl_getinfo($query, CURLINFO_RESPONSE_CODE), according to the manual.

Sorry, it was very late. I meant that the 409 page is not in XML format. Checking for the status code didn't occur to me, because I was falling asleep.

Thank you so much for the detailed description and wonderful ideas!

[Trotterdam]

Again, look at the flowchart in the documentation. Autologin is only checked if your PIN is invalid, which will happen all the time, because PINs are being invalidated constantly (anytime you log in elsewhere, anytime you go two hours without doing anything).

None of this is in the documentation. The flowchart is nice, of course, but it doesn't say how to check for X-Pin validity. The documentation should really be more clear on that.

You don't check the X-Pin for validity. You send it regardless of if it's valid or not (unless it's a completely empty string), and the server will automatically ignore it, and fall back to the X-Password and/or X-Autologin that you supplied at the same time, if it's invalid. Similarly, you always check the server's response for a new X-Pin, which, if supplied, automatically implies your previous one is invalid and should be replaced.

How would you identify a valid X-Autologin? Compare it to an empty string?

Yeah, that. Remember that the very next step amounted to "if the server complained your autologin was invalid, get a new one", so it's not a huge deal if you try to use an autologin you're not sure about. This is just to save you from sending a request that's really obviously not going to work.

(This is, of course, for my original approach to a program that is able to receive user input. Since you can't, it isn't too relevant to you.)

save the former to disk

When you say "save to disk", what exactly do you mean? Saving it to a file? What's the advantage of that compared to having the value in plaintext inside the script itself?

Well, for one, that you're sure you're using the autologin correctly. It also lets the script update itself if you change your nation's password, rather than needing to muck with your code again every time that happens.

If you were writing the script for anyone else, it would also make it more user-friendly by not requiring any user input that requires technical expertise (since the only user input is the password like you'd type on a normal login, not autologin). Maybe not a concern for your use case, but something I try to think about.

prompt the user to enter a password

That doesn't really work for me, as I am running it from my server's crontab. It doesn't receive any user input.

Oh, hmm. I guess you are stuck with hardcoding (or at least supplying in a non-interactive configuration file, which amounts to the same thing) either your password or your autologin, in that case. I still suggest you try to get your autologin from the X-Autologin header returned by a (possibly manual, but ideally from the same computer that's running the script) API request, rather than directly from your browser's cookies, just in case. If they are exactly the same, then at least checking it rules out one possible source of error.

Ah, I just read your post again and saw that you're already doing something close to this:

I have a separate login.php script that I grab the X-Pin and X-Autologin from by running it manually once. It seemed ridiculous to me (and it still does) to check if the X-Pin is "current" for every bloody API command. It's 1 additional API request that is completely unnecessary given the "rigorous" system we're dealing with. According to the documentation, the whole point of having an X-Pin is so that you don't have to authenticate every time you issue an API command. Otherwise the easiest way for me to send them is by simply using X-Password and ignoring the other custom headers.

That's not quite right, though. Your login.php should only grab the X-Autologin. X-Pins expire too frequently to be useful "prepackaged", and should be constantly checked in your main script, not your login.php.

You shouldn't need any additional API requests for this. Each request you make should give you a new X-Pin for free, if you need one.

The cURL manual shows that you can get both the header and the XML text in one request like this:

Code: Select all

curl_setopt($ch, CURLOPT_HEADER, true);
$response = curl_exec($ch);
$curl_info = curl_getinfo($ch); // Equivalently, $header_size = curl_getinfo($ch, CURLINFO_HEADER_SIZE); should also work.
curl_close($ch);
$header_size = $curl_info['header_size'];
$header = substr($response, 0, $header_size);
$body = substr($response, $header_size);

I guess you will then need to do some string processing to locate a line in $header that starts with "X-Pin: ", and if found, update the X-Pin that you send on subsequent requests to match. Then process $body as you normally do. Checking the HTTP response code (curl_getinfo($ch, CURLINFO_RESPONSE_CODE) or $curl_info['http_code']) should be done after you process $header but before you process $body (continuing with the latter only if the response code is equal to 200).

[Darcania]

Just noticed that for the API documentation, under the World API section, there's a duplicate number 6 footnote, one for happenings and another for regionsbytag.

[Aibohphobia]

You don't check the X-Pin for validity. You send it regardless of if it's valid or not (unless it's a completely empty string), and the server will automatically ignore it, and fall back to the X-Password and/or X-Autologin that you supplied at the same time, if it's invalid. Similarly, you always check the server's response for a new X-Pin, which, if supplied, automatically implies your previous one is invalid and should be replaced.

That's too much trouble. It's easier to always use X-Password or always renew X-Pin without checking its validity. Additionally, as noted before, the current API commands do not work if a valid X-Autologin is provided. They require a valid X-Pin or X-Password.

Well, for one, that you're sure you're using the autologin correctly. It also lets the script update itself if you change your nation's password, rather than needing to muck with your code again every time that happens.

If you were writing the script for anyone else, it would also make it more user-friendly by not requiring any user input that requires technical expertise (since the only user input is the password like you'd type on a normal login, not autologin). Maybe not a concern for your use case, but something I try to think about.

Those are all very good points. I concur.

I guess you are stuck with hardcoding (or at least supplying in a non-interactive configuration file, which amounts to the same thing)

It's really annoying, because it completely removes the layer of security X-Autologin and X-Pin are supposed to provide.
I can easily create a user-friendly configuration page, but it's hardly a big advantage over pasting one's password into a text file. Another solution would be to ask for a password parameter to the PHP script itself, but that would put the password in plain text into the URL which is even further from being ideal. Cryptographic functions could be used to encrypt the contents of the password file, but I'll have to think about it. It's not like I can easily distinguish between encrypted and non-encrypted files, unless I use different extensions, file names or file formats, which, I feel, goes above the initial scope of this project.

X-Pins expire too frequently to be useful "prepackaged", and should be constantly checked in your main script, not your login.php.

The next iteration of the script will remove login.php completely, as I will have to revise the logic behind it after receiving your feedback.

I guess you will then need to do some string processing to locate a line in $header that starts with "X-Pin: ", and if found, update the X-Pin that you send on subsequent requests to match. Then process $body as you normally do. Checking the HTTP response code (curl_getinfo($ch, CURLINFO_RESPONSE_CODE) or $curl_info['http_code']) should be done after you process $header but before you process $body (continuing with the latter only if the response code is equal to 200).

I know how to separate headers from body, but I appreciate you quoting the code. I will indeed have to do just that... Thank you very much for your continued help.