API v3 (GraphQL)

Politics and War API v3

Version 3 of Politics and War's Application Programming Interface (API) is GraphQL-based. For those who may not know, "GraphQL is a query language for APIs and a runtime for fulfilling those queries with your existing data." It is highly encouraged that you spend time learning how to structure GraphQL requests before attempting to get data from the API. One method of doing so is by tinkering around in PnW's GraphQL Playground, which is discussed in more detail below.

About the Playground

Accessing

You can access the GraphQL playground here and use it to test queries. When you first enter the playground, the API's base URL should be visible in the search bar of the playground; this URL is: https://api.politicsandwar.com/graphql. To get started, you will want to append ?api_key= and then your API key to the end of this URL to make it look like this: https://api.politicsandwar.com/graphql?api_key=your_key_here. If you don't know your API key, it can be found here (under Account -> API Key). It is important that you only share your API key with those you trust.

Contents

On the left, you will see a blank area where you can craft your query. On the right, you will see a blank area where the response to your query will be when the play button is hit. On the far right, you should see two tabs: Docs and Schema. These are essentially the same thing, but the Docs tab is a more accessible view of the API's schema. The first layer you will be greeted with on the Docs tab is a column titled "Queries," and this lists all of the endpoints that you can query and the mutations you can perform through the API. Let's look at the nations endpoint as an example. Clicking that endpoint allows us to view the different arguments we can pass to it in order to narrow our query—at the bottom of this column, we can view more details about each argument—and what is returned by this endpoint (in this case, it is a NationPaginator that contains paginatorInfo and data). Clicking into the data section of the NationPaginator, we are able to view all of the fields that we can query from the nations endpoint (clicking them will give more information).

Crafting Queries

Let's say we want to get the name of the nation with the ID number 244934. Based on the description above, you may rightly assume that this information is under nations -> data -> nation_name, but what does a query to access that actually look like? This is what that query would look like:

{
  nations(id:244934){
    data{
      nation_name
    }
  }
}

This is an extremely basic example, though. Let's look at a more complex query and break it down:

{
  Aurora: nations(alliance_id:4648, color:"gray", orderBy:{column:SCORE, order:ASC}){
    data{
      id
      nation_name
      last_active
    }
  }
  Borealis: nations(alliance_id:8804, color:"gray"){
    data{
      id
      nation_name
      last_active
    }
  }
}

The "Aurora:" and "Borealis:" in front of each endpoint query are known as aliases, which must be done if you're querying the same endpoint in two different ways. Here, the first query gets all nations who are in Aurora (ID 4648) and on the Gray color bloc then returns them in ascending order by score while the second query gets all nations who are in Borealis (ID 8804) and on the Gray color bloc (but does not return them sorted). These two queries happen to return the same data about the nations, but you could request different data instead.

These examples are not meant to show every single aspect of how to query the API, but hopefully they provide guidance and you can generalize to the rest of the documentation.

Implementation

Querying the API via your code may look different from one developer to another, but here are some potentially helpful resources.

Via Link

Recall that the base URL for the v3 API is https://api.politicsandwar.com/graphql. Querying the API via link involves two simple steps: appending ?api_key=your_key_here and then &query=your_query_here to the base URL. So, the full link should look something like this: https://api.politicsandwar.com/graphql?api_key=your_key_here&query=your_query_here. Getting your query is as simple as copying the query you were tinkering with in the Playground (like the ones above).

Example: https://api.politicsandwar.com/graphql?api_key=your_key_here&query={nations(id:244934){data{nation_name}}}

You can then use this link in whatever language or library you like (i.e.: requests in Python, fetch in JavaScript, cURL in PHP, etcetera).

Python

For Python, there is pnwkit-py developed by Village, which has robust documentation and is fairly easy to implement. It is worth noting that this is strictly a wrapper for the API and does not provide any additional methods or helper functions. There is also PnP developed by Star-Tube, but to my knowledge the veracity and robustness of this wrapper have not been well tested.

JavaScript

For JavaScript, there is pnwkit developed by bsnk-dev, which also has documentation available. There is also pnwkit-2.0 developed by darkblade, which is more up to date with any recent (as of July 2023) API updates.

Other

For Google App Scripts, there is pnwkit.gs developed by bsnk-dev, which (like other pnwkit projects) has documentation available.

Documentation

Documentation is available in the Playground (as mentioned above) and at the provided locations for the above mentioned wrappers. However, there are also a few miscellaneous documentations that shall be listed here as they are found:

• Village's GitBook - Village has provided here some useful introductory information as well as some information that is not currently covered here regarding mutations and subscriptions

Getting Help

One of the best places to get help regarding the API, or just development/coding in general, is the Politics and Development Discord server. There are a wide variety of developers from different backgrounds and with differing expertise in the community who are willing to help you.