Jump to content

Improved API Access


Alex
 Share

Recommended Posts

  • Administrators

Long awaited and long discussed, I'm putting forth some changes to how the API works, to reduce spam requests and to allow more access based on your nation's permissions.

 

These changes are currently being tested on http://alex.politicsandwar.com

 

Basically how the system works is that everyone has a unique API key for their nation. This API key is required to access API pages, and each time you access a page a request is logged. By default, each nation is allowed 10,000 requests per day. At the end of the day, your requests is reset to 0. VIP Subscribers have a limit of 999,999 requests per day.

 

Once this is up and running, I'll be adding more API pages and providing more relevant information based on user permissions. I.E. If you're an alliance leader or heir, you'll have access to all of the warchest information for members in your alliance. Stuff like that that should be super useful for planning and using scripts to collect data for analysis.

 

I'm willing to negotiate with the default allowed requests per day, but I can't imagine anyone except hardcore API users using more than 10,000/day, and if you are a hardcore API user, I think you should be willing to pay for VIP to have access to the service.

 

Please help me test it and make sure it's working correctly at http://alex.politicsandwar.combefore I push it live.

 

To use your API key, make a request like normal but include /key={INSERT KEY HERE} at the end of your request.

  • Upvote 6

Is there a bug? Report It | Not understanding game mechanics? Ask About It | Got a good idea? Suggest It

Forums Rules | Game Link

Link to comment
Share on other sites

  • Administrators

An example of how the key benefits users, I just created a new page that lets you get the contents of your alliance bank.

 

Page URL: 

http://alex.politicsandwar.com/api/alliance/bank/contents/ALLIANCEID/key=KEY

Trying to access a non-existent alliance:

 

{ "success":false, "general_message":"Alliance does not exist." }

 

Trying to access an alliance you're not in:

 

{ "success":false, "general_message":"Unable to access. You are not in this alliance." }

 

Trying to access an alliance you're in, but don't have permissions to view the bank:

 

{ "success":false, "general_message":"Your alliance settings have not made the bank contents information available to you." }

 

And an example of a successful result:

 

{ "success": true, "alliance_bank_contents": [{"alliance_id":2385,"name":"War Doves","taxrate":0,"resource_taxrate":75,"money":904.72,"food":4849299.27,"coal":137844.02,"oil":133467,"uranium":33813.41,"iron":16673.16,"bauxite":11167.7,"lead":946,"gasoline":774703.54,"munitions":792338,"steel":455722.66,"aluminum":847158}] }

Is there a bug? Report It | Not understanding game mechanics? Ask About It | Got a good idea? Suggest It

Forums Rules | Game Link

Link to comment
Share on other sites

I haven't phisically tried it yet but two things came to mind:

 

1) we need to know how many requests we have left. Generally this information is given in the header in a X-Rate-Limit-Remaining field.

 

2) Once this is going to be implemented on the live server, we need probably at least a weeks notice before so we all know the exact date and can have time to update our programs properly.

  • Upvote 1

[22:37:51] <&Yosodog> Problem is, everyone is too busy deciding which top gun character they are that no decision has been made

 

BK in a nutshell

Link to comment
Share on other sites

  • Administrators

I haven't phisically tried it yet but two things came to mind:

 

1) we need to know how many requests we have left. Generally this information is given in the header in a X-Rate-Limit-Remaining field.

 

2) Once this is going to be implemented on the live server, we need probably at least a weeks notice before so we all know the exact date and can have time to update our programs properly.

 

One the first point, it does say on your Account page. But I imagine you mean you'd like it to output upon each request, which seems reasonable to me.

 

On the second point, I agree. Part of why I'm bringing it up here and now, to alert everyone of the upcoming change beforehand. I'm not in a rush to push it live yet, but I'd like to create awareness.

Is there a bug? Report It | Not understanding game mechanics? Ask About It | Got a good idea? Suggest It

Forums Rules | Game Link

Link to comment
Share on other sites

Once this is up and running, I'll be adding more API pages and providing more relevant information based on user permissions. 

 

If you could make all the relevant war information (damage, loot, losses, etc.) available in the API, more people would probably secure VIP to access it. 

 

https://politicsandwar.com/forums/index.php?/topic/19238-the-war-api/

 

Pretty please Alex?

  • Upvote 1

"To give anything less than your best is to sacrifice the gift." ~ Prefontaine


Pure Gold, ~KT chat:


 

Link to comment
Share on other sites

The only issue I have with the number of requests, is that there are currently 149 alliances and 5263 nations in the game, with 29,146 cities. So I currently make somewhere in excess of 35,000 requests. Or anyone else crazy enough to be requesting information on everything. I probably could limit some of it to the top 50 alliances, but it's actually more effort to restrict it that way.

A few things would potentially drop that number.

  • My suggestion of fixing the nation and alliance API, so that the single and list API all contain the same information (which IMO is good practice). This would mean I would only have to make 2 requests for the pieces of information I gather, instead of 5,412 requests.
  • Allow lookup of cities by nation /api/nation/<id>/cities/ which would reduce the requests I would have to make for all the city information, to 5,263.
  • Allow multiple IDs to be passed, up to a maximum of say 10. So /api/nation/1,2,3/ would return back the details for nations with the IDs of 1, 2 and 3 (in a json array).

I also have an issue with your bank API structure, it should imo read /api/alliance/<id>/bank/current/ and it should only contain the bank contents. Alliance ID/Name are redundant and the tax rates should be elsewhere (possibly under /api/alliance/<id>/tax/).

 

I do like the new error messages though and I'll test your rate limit over the weekend, see whether it locks me out and then kicks back in after update.

 

Side note: If you're after any more thoughts about how the various APIs should be structured, drop me a message on Discord. I'm not always around, but I check it on and off throughout my day. Though you've possibly seen some of my previous posts on the forums here and from the notes above, you can probably work out what some of those thoughts would be.

  • Upvote 1

sig_cybernations.PNG.8d49a01423f488a0f1b846927f5acc7e.PNG

Link to comment
Share on other sites

  • Administrators

I should like to try out this new api, but /api/nations/ doesn't return anything. Can we get what all links will be in future?

 

That's the right link - you need to append your API key.

Is there a bug? Report It | Not understanding game mechanics? Ask About It | Got a good idea? Suggest It

Forums Rules | Game Link

Link to comment
Share on other sites

That's the right link - you need to append your API key.

 

I guess a 404 when you don't put a key not very good, maybe some "success: false" should be adequate. It should show anyone that without a key, it doesn't works.

 

Okay, for /api/nations/ it's "/api/nations/key=xxx"

 

What about /api/nation/?

 

I have tried:

/api/nation/1000/key=xxx

/api/nation/id=1000&key=xxx

/api/nation/id/1000/key=xxx

 

Can we have a example for each URL?

Link to comment
Share on other sites

Firstly, thank you for doing this. The API is an incredibly useful tool, but it needs some major work. I don't want to tell you what to do, but here are some things that I hope you keep in mind.
 
Major items:

  • Don't break things. Please don't break things. If you take one thing away from this post, please don't break things. Every endpoint should be versioned (e.g. /api/nations/v1/key=KEY). Any time you make any change, bump the version. Recognizing that the server has limited resources, I don't expect all versions to be available forever. Just make the new version live a few weeks before you take down the old one, to give people time to adjust (like you are now :) ).
  • Consistency. Please take the time to do some reading regarding API best practices. There are plenty of conventions that make life easier for both you and your users. At the very least, establish a convention and then always follow it. Some specific grievances in that regard:
    • Always serve numbers as numbers, not sometimes numbers and sometimes strings.
    • Choose camelCase, snake_case, or lowercase and stick with it. Avoid arbitrary and confusing abbreviations. Use concise yet descriptive keys wherever possible.
    • Pick an endpoint style and stick with it. Don't mix use of /endpoint1/id=123 and /endpoint2/456.
  • Documentation. There's no official list anywhere of what APIs are available, and new ones seem to be added without any fanfare or announcement.

Minor items:

  1. Make use of HTTP headers. Don't serve 200 if there's an error. Set response type to application/json (which you have on the test server). Use it to serve relevant information, like X-Rate-Limit-Remaining (and X-Rate-Limit-Reset), like Yosodog suggested above.
  2. The API key should be sent as a header, not as part of the URL. This makes it much less likely for somebody to accidentally share their key and have somebody else abuse it.
  3. Give people the ability to generate a new API key, in case they do accidentally share it.
  4. As Shakyr mentioned above, anyone who wants to get a full snapshot of the game must make 35,000+ requests. As one of the people who presently does that, it would make my life a lot easier (and significantly reduce the load on the server) if a full snapshot were to be made available as a static resource, updated once or twice daily.

I hope you take the time to consider these things, and use them to create a polished, consistent product. Thanks.

 

PS: Shameless plug for my P&W Coding Discord server.

RollSheepy.png

Link to comment
Share on other sites

I haven't had a chance to test this yet due to being on mobile, but does this include a transaction / tax transaction api for the bank? Current balances all well and good, but the ability to track movements is what will actual provide some functionality to this.

 

Apologies if it already exists and I missed it; seconding the need for an official API documentation and the need for standard practice.

Link to comment
Share on other sites

We cannot really test anything if there is no URLs for us to test.

 

There is one more thing, right now, "/api/nations/" just works normally like in live server in "http://alex.politicsandwar.com/api/nations/".

 

One the first point, it does say on your Account page. But I imagine you mean you'd like it to output upon each request, which seems reasonable to me.

 

On the second point, I agree. Part of why I'm bringing it up here and now, to alert everyone of the upcoming change beforehand. I'm not in a rush to push it live yet, but I'd like to create awareness.

 

Just push it live, and make everyone suffer, it's gonna happen anyways, no need for fake awareness feeling.

 

If the API is something that makes game suffer in performance, just kill the API or parts of it that are suffering performance issues. This is better than having issues with war and losing MAPs.

Link to comment
Share on other sites

  • 6 months later...

Join the conversation

You can post now and register later. If you have an account, sign in now to post with your account.

Guest
Reply to this topic...

×   Pasted as rich text.   Paste as plain text instead

  Only 75 emoji are allowed.

×   Your link has been automatically embedded.   Display as a link instead

×   Your previous content has been restored.   Clear editor

×   You cannot paste images directly. Upload or insert images from URL.

Loading...
 Share

  • Recently Browsing   0 members

    • No registered users viewing this page.
×
×
  • Create New...

Important Information

By using this site, you agree to our Terms of Use and the Guidelines of the game and community.