Script Rules Update

[United Calanworie]

We are looking to update the script rules in a minor fashion here to clarify HTML scripter responsibility to use the API, and this is the current proposed wording:

In a case where the API is capable of delivering the data that you are requesting (e.g. a stat query, dispatch text lookup) you must use the available API endpoint and you may not target the HTML site with a script.

If you have comments, please leave them below. There is no current timeframe for us to make this change, but any change will have a notification period and grace period attached.

[Esfalsa]

Where in the script rules would that be added? That would be helpful to know to contextualize this change.

Off the bat though, I think it would be better to provide greater clarity about what 'data' is being 'delivered,' as referenced in this rule. For instance:

• I assume this is not the intention if this is meant as a 'minor' or 'clarifying' change, but I think a plain reading of this proposed wording would suggest scripts to open the issue page would become illegal? The list of what issues currently confront a nation is available on the API, but the reason why card farmers open the issues page is to answer issues on the HTML site. Unless you count the chance to earn a pack of cards as data being delivered, answering an issue on the HTML site doesn't deliver any data that answering an issue with the API doesn't also deliver. That seems... pretty major for anyone who farms cards.
• I similarly assume this is not the intention, but in R/D, the only way 'chasing' is a viable form of gameplay is because the reports page delivers happenings in more or less real time. Technically, that data is available from the API (with multiple requests) on a 28-second delay, but I'm sure anyone in R/D can tell you that chasing on a 28 second delay is completely infeasible. On some level, this feels more pedantic than the last example, but on another level — here, it's the exact same data being delivered, and the proposed rule makes no exception if the API is capable of delivering the data you are requesting, but not with an analogous endpoint and not until after so long a delay that the data is useless.

On another note, I don't know if it needs a carve-out in the rules, but there have been situations in the past where some API functionality is perhaps well-known among certain script author communities but isn't actually documented (but hey, the RMB posting private command is documented now — thanks!). Furthermore, the API has no changelog (as far as I know, not even a standing policy to announce when a new version is live?) and I can't really discern a versioning policy from the documentation other than that "older versions may stop working without notice." I'm not trying to nitpick here or to demand semver or something, but I do assume handing out punishments for situations where the script author is reasonably unaware that the API has that functionality is not the spirit of this rule — that's distinct from fixing the script once contacted and made aware.

[United Calanworie]

Where in the script rules would that be added? That would be helpful to know to contextualize this change.

Fair point. This would insert under "Deprecation Notice," addending the line that says "Note!! Tools that interact with the server should use the NationStates API, rather than sending commands to the HTML site."

Off the bat though, I think it would be better to provide greater clarity about what 'data' is being 'delivered,' as referenced in this rule. For instance:

• I assume this is not the intention if this is meant as a 'minor' or 'clarifying' change, but I think a plain reading of this proposed wording would suggest scripts to open the issue page would become illegal? The list of what issues currently confront a nation is available on the API, but the reason why card farmers open the issues page is to answer issues on the HTML site. Unless you count the chance to earn a pack of cards as data being delivered, answering an issue on the HTML site doesn't deliver any data that answering an issue with the API doesn't also deliver. That seems... pretty major for anyone who farms cards.
• I similarly assume this is not the intention, but in R/D, the only way 'chasing' is a viable form of gameplay is because the reports page delivers happenings in more or less real time. Technically, that data is available from the API (with multiple requests) on a 28-second delay, but I'm sure anyone in R/D can tell you that chasing on a 28 second delay is completely infeasible. On some level, this feels more pedantic than the last example, but on another level — here, it's the exact same data being delivered, and the proposed rule makes no exception if the API is capable of delivering the data you are requesting, but not with an analogous endpoint and not until after so long a delay that the data is useless.

Thanks for those notes. I'll have to get back to you on the first one, but as to the second, I've actually opened a PR to remove the happenings delay from the API, plus we have a SSE server in the works for happenings. Both of those should produce a result where the HTML page no longer needs to be consumed for chasing.

On another note, I don't know if it needs a carve-out in the rules, but there have been situations in the past where some API functionality is perhaps well-known among certain script author communities but isn't actually documented (but hey, the RMB posting private command is documented now — thanks!). Furthermore, the API has no changelog (as far as I know, not even a standing policy to announce when a new version is live?) and I can't really discern a versioning policy from the documentation other than that "older versions may stop working without notice." I'm not trying to nitpick here or to demand semver or something, but I do assume handing out punishments for situations where the script author is reasonably unaware that the API has that functionality is not the spirit of this rule — that's distinct from fixing the script once contacted and made aware.

Yes, I've been working slowly to improve API documentation, but I can see a good case being made here for us being more intentional about our API versioning.

[Trotterdam]

There should probably be a grace period when a new feature gets added to the API, because you can't expect people to update their scripts overnight. (And sometimes the feature needs debugging before it's practical to use.)

[9003]

With a bigger push to get everything on the API, does the staff plan on or is their merit to having someone on the tech team specialize in the API. Specifically adding new nodes to the API or is that to niche thing.

[United Calanworie]

Nobody needs to specialize, as it were, in adding things to the API. That’s not a concern for us.

[United Calanworie]

There should probably be a grace period when a new feature gets added to the API, because you can't expect people to update their scripts overnight. (And sometimes the feature needs debugging before it's practical to use.)

Thanks, this would make sense. I’m not sure how we would word this in the script rules, but it should probably be inserted in some way.

[United Calanworie]

I’m bumping this to note that with the rollout of SSE, we’re looking at this some more. Does anybody else have thoughts?

[Omnicontrol]

Yeah, I do: I wouldn't like to see going to the HTML issues list page to answer issues instead of the API one be illegal as I (and many other card farmers) very much do not want to card farm manually

[9003]

Yeah, I do: I wouldn't like to see going to the HTML issues list page to answer issues instead of the API one be illegal as I (and many other card farmers) very much do not want to card farm manually

Gotissues (The script in your question) should be okay as it "harvests" the issue data via the API first to craft the custom URL that then lets the user script highlight the first option so you can press enter and breeze through.

My reading of the rule would allow this as GI, does not use the HTML to gather data and rather uses it to "print cards/answer issues" where the API would only be able to answer issues.

[United Calanworie]

Yeah, I do: I wouldn't like to see going to the HTML issues list page to answer issues instead of the API one be illegal as I (and many other card farmers) very much do not want to card farm manually

Gotissues (The script in your question) should be okay as it "harvests" the issue data via the API first to craft the custom URL that then lets the user script highlight the first option so you can press enter and breeze through.

My reading of the rule would allow this as GI, does not use the HTML to gather data and rather uses it to "print cards/answer issues" where the API would only be able to answer issues.

This is a correct reading. If the script is gathering the data from the API and then you are answering on the HTML page (without using a script, i.e. you are manually clicking the answer button each time) you would be in compliance with the rule.