Administrators Alex Posted April 26, 2017 Administrators Share Posted April 26, 2017 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. 6 Quote Is there a bug? Report It | Not understanding game mechanics? Ask About It | Got a good idea? Suggest ItForums Rules | Game Link Link to comment Share on other sites More sharing options...
Administrators Alex Posted April 26, 2017 Author Administrators Share Posted April 26, 2017 You can find your API key on the Account page (at the bottom) Quote Is there a bug? Report It | Not understanding game mechanics? Ask About It | Got a good idea? Suggest ItForums Rules | Game Link Link to comment Share on other sites More sharing options...
Administrators Alex Posted April 26, 2017 Author Administrators Share Posted April 26, 2017 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}] } Quote Is there a bug? Report It | Not understanding game mechanics? Ask About It | Got a good idea? Suggest ItForums Rules | Game Link Link to comment Share on other sites More sharing options...
Yosodog Posted April 26, 2017 Share Posted April 26, 2017 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. 1 Quote [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 More sharing options...
Administrators Alex Posted April 26, 2017 Author Administrators Share Posted April 26, 2017 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. Quote Is there a bug? Report It | Not understanding game mechanics? Ask About It | Got a good idea? Suggest ItForums Rules | Game Link Link to comment Share on other sites More sharing options...
Khorne Posted April 26, 2017 Share Posted April 26, 2017 ALEX I LOVE YOU MARRY ME 1 Quote "To give anything less than your best is to sacrifice the gift." ~ Prefontaine Pure Gold, ~KT chat: Link to comment Share on other sites More sharing options...
Avruch Posted April 26, 2017 Share Posted April 26, 2017 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. 1 Quote Link to comment Share on other sites More sharing options...
Khorne Posted April 26, 2017 Share Posted April 26, 2017 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? 1 Quote "To give anything less than your best is to sacrifice the gift." ~ Prefontaine Pure Gold, ~KT chat: Link to comment Share on other sites More sharing options...
Shakyr Posted April 26, 2017 Share Posted April 26, 2017 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. 1 Quote Link to comment Share on other sites More sharing options...
Kosonome Posted April 28, 2017 Share Posted April 28, 2017 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? Quote Link to comment Share on other sites More sharing options...
Administrators Alex Posted April 28, 2017 Author Administrators Share Posted April 28, 2017 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. Quote Is there a bug? Report It | Not understanding game mechanics? Ask About It | Got a good idea? Suggest ItForums Rules | Game Link Link to comment Share on other sites More sharing options...
Kosonome Posted April 30, 2017 Share Posted April 30, 2017 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? Quote Link to comment Share on other sites More sharing options...
Kid Winchell Posted April 30, 2017 Share Posted April 30, 2017 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: 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. 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. Give people the ability to generate a new API key, in case they do accidentally share it. 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. Quote Link to comment Share on other sites More sharing options...
Timmy Posted April 30, 2017 Share Posted April 30, 2017 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. Quote Link to comment Share on other sites More sharing options...
Kosonome Posted May 3, 2017 Share Posted May 3, 2017 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. Quote Link to comment Share on other sites More sharing options...
Neymar Posted November 17, 2017 Share Posted November 17, 2017 "Alex" What you say is true Quote Link to comment Share on other sites More sharing options...
Recommended Posts
Join the conversation
You can post now and register later. If you have an account, sign in now to post with your account.