NATION

PASSWORD

[API] Java Wrapper for the NS API (updated August 16th, '20)

Bug reports, general help, ideas for improvements, and questions about how things are meant to work.
User avatar
Agadar
Powerbroker
 
Posts: 7786
Founded: Dec 06, 2009
Psychotic Dictatorship

[API] Java Wrapper for the NS API (updated August 16th, '20)

Postby Agadar » Mon Jul 11, 2016 4:26 pm

[ Agadar's Java Wrapper for the NationStates API ]

This Java library provides programmers with an easy way to communicate with the NationStates API. It supports the following basic functionalities:

  • Retrieving information about Nations, Regions, the World Assembly, and the World;
  • Downloading and reading daily data dumps;
  • Sending telegrams;
  • Verifying users.
On top of the basic functionalities, this wrapper also ensures the mandated rate limits are not violated, and gives warnings when the wrapper itself is outdated, so that you don't have to worry about any of those things.

[ Basics ]

Instantiating a NationStates object and setting a User Agent is the first thing you'll have to do, ensuring NationStates admins can identify your script:

Code: Select all
NationStates nationStates = new DefaultNationStatesImpl("Example Nation's Script (example@example.com)");

That's all you need to do to be able to use the wrapper! Now we can, say, retrieve the national animal name of a nation:

Code: Select all
Nation nation = nationStates.getNation("agadar").shards(NationShard.ANIMAL).execute();

This gives us a Nation object holding the animal name. That's all there is to it! All queries are build and executed in a similar fashion.

[ Custom return types ]

The 'Nation' class and other such domain classes have little to no methods: they exist solely to hold the information you request from the NationStates API. If you want to add methods, then you can inherit the domain classes or create entirely seperate ones and tell the wrapper to use your custom domain classes instead.

For example, imagine we create a class 'CustomNation' that inherits 'Nation' but which holds some handy methods not natively present in the 'Nation' class. We then first register our custom class so that it is recognized:

Code: Select all
nationStates.registerTypes(CustomNation.class);

Now whenever we want a Nation-query to return our custom type, we can use the overloaded execute()-function, like so:

Code: Select all
CustomNation nation = nationStates.getNation("agadar").shards(NationShard.ANIMAL).execute(CustomNation.class);

And voilĂ : we now have an instance of our custom class, holding the retrieved animal name.

[ Links ]

Releases
Source code
NationStates API documentation
More applications
Last edited by Agadar on Sun Aug 16, 2020 1:43 pm, edited 14 times in total.
Proud resident of The Western Isles, the #1 role-playing region!
Developer of Telegrammer, NS API Java Wrapper, and more!

User avatar
Agadar
Powerbroker
 
Posts: 7786
Founded: Dec 06, 2009
Psychotic Dictatorship

Postby Agadar » Wed Jul 13, 2016 7:22 pm

Just released version 1.1.0. Might be a few hours until it shows up over at mvnrepository.
Proud resident of The Western Isles, the #1 role-playing region!
Developer of Telegrammer, NS API Java Wrapper, and more!

User avatar
Agadar
Powerbroker
 
Posts: 7786
Founded: Dec 06, 2009
Psychotic Dictatorship

Postby Agadar » Mon Sep 05, 2016 12:40 pm

Version 1.2.0 now available. See the 'Releases' link in the OP.
Proud resident of The Western Isles, the #1 role-playing region!
Developer of Telegrammer, NS API Java Wrapper, and more!

User avatar
Agadar
Powerbroker
 
Posts: 7786
Founded: Dec 06, 2009
Psychotic Dictatorship

Postby Agadar » Sat Feb 04, 2017 10:03 am

Released version 2.0.0. See the 'Releases' link in the OP for the changelog and downloads.
Proud resident of The Western Isles, the #1 role-playing region!
Developer of Telegrammer, NS API Java Wrapper, and more!

User avatar
Agadar
Powerbroker
 
Posts: 7786
Founded: Dec 06, 2009
Psychotic Dictatorship

Postby Agadar » Mon Dec 25, 2017 6:34 pm

Released version 3.0.0. See the 'Releases' link in the OP for the changelog and downloads.
Proud resident of The Western Isles, the #1 role-playing region!
Developer of Telegrammer, NS API Java Wrapper, and more!

User avatar
Agadar
Powerbroker
 
Posts: 7786
Founded: Dec 06, 2009
Psychotic Dictatorship

Postby Agadar » Sun Mar 04, 2018 8:56 am

Released version 4.0.0. See the 'Releases' link in the OP for the changelog and downloads.
Proud resident of The Western Isles, the #1 role-playing region!
Developer of Telegrammer, NS API Java Wrapper, and more!

User avatar
Agadar
Powerbroker
 
Posts: 7786
Founded: Dec 06, 2009
Psychotic Dictatorship

Postby Agadar » Sat Dec 22, 2018 9:11 am

Released version 5.0.0. See the 'Releases' link in the OP for the changelog and downloads.
Proud resident of The Western Isles, the #1 role-playing region!
Developer of Telegrammer, NS API Java Wrapper, and more!

User avatar
Agadar
Powerbroker
 
Posts: 7786
Founded: Dec 06, 2009
Psychotic Dictatorship

Postby Agadar » Wed Oct 30, 2019 5:16 pm

Released version 5.1.0. See the 'Releases' link in the OP for the changelog and downloads.
Proud resident of The Western Isles, the #1 role-playing region!
Developer of Telegrammer, NS API Java Wrapper, and more!

User avatar
Agadar
Powerbroker
 
Posts: 7786
Founded: Dec 06, 2009
Psychotic Dictatorship

Postby Agadar » Wed Nov 20, 2019 4:26 pm

Released version 6.0.0. See the 'Releases' link in the OP for the changelog and downloads.
Proud resident of The Western Isles, the #1 role-playing region!
Developer of Telegrammer, NS API Java Wrapper, and more!

User avatar
Agadar
Powerbroker
 
Posts: 7786
Founded: Dec 06, 2009
Psychotic Dictatorship

Postby Agadar » Sun Aug 16, 2020 1:42 pm

Released version 7.0.0. See the 'Releases' link in the OP for the changelog and downloads.
Proud resident of The Western Isles, the #1 role-playing region!
Developer of Telegrammer, NS API Java Wrapper, and more!

User avatar
Repolet
Political Columnist
 
Posts: 2
Founded: Dec 18, 2021
Ex-Nation

Postby Repolet » Tue Aug 01, 2023 6:59 pm

Hi, Agadar!

Sorry, I just have a question regarding version 7.0.0... the files in the "Resources" page that correspond to 7.0.0 are both Source codes, but where can I find the app where I'll be interacting with the API? Should I use the one from 6.0.0?

Thanks,
Repolet

User avatar
Agadar
Powerbroker
 
Posts: 7786
Founded: Dec 06, 2009
Psychotic Dictatorship

Postby Agadar » Fri Aug 04, 2023 5:31 am

Repolet wrote:Hi, Agadar!

Sorry, I just have a question regarding version 7.0.0... the files in the "Resources" page that correspond to 7.0.0 are both Source codes, but where can I find the app where I'll be interacting with the API? Should I use the one from 6.0.0?

Thanks,
Repolet


Hello Repolet, seems to be a misconception: this Java Wrapper is a library that can be used by other applications (such as my own Telegrammer application) to communicate with the NS API. It is not something that you can just download by itself and use as if it were an application. It only facilitates access for other applications. I hope that clears it up.
Proud resident of The Western Isles, the #1 role-playing region!
Developer of Telegrammer, NS API Java Wrapper, and more!

User avatar
Repolet
Political Columnist
 
Posts: 2
Founded: Dec 18, 2021
Ex-Nation

Postby Repolet » Fri Aug 04, 2023 2:39 pm

Agadar wrote:
Repolet wrote:Hi, Agadar!

Sorry, I just have a question regarding version 7.0.0... the files in the "Resources" page that correspond to 7.0.0 are both Source codes, but where can I find the app where I'll be interacting with the API? Should I use the one from 6.0.0?

Thanks,
Repolet


Hello Repolet, seems to be a misconception: this Java Wrapper is a library that can be used by other applications (such as my own Telegrammer application) to communicate with the NS API. It is not something that you can just download by itself and use as if it were an application. It only facilitates access for other applications. I hope that clears it up.

It certainly does, thank you!


Advertisement

Remove ads

Return to Technical

Who is online

Users browsing this forum: East Chimore

Advertisement

Remove ads