api-swgoh-help's Introduction

api-swgoh-help

Java client wrapper for the API at https://api.swgoh.help

Due to the extreme versatility of this API and the available options that are given that modify the response structures, all of the responses returned by each endpoint will be raw JSON in the form of a java.lang.String for now. The consumer of this API client is then free to parse the data into whatever form they choose.

Usage

Include the swgoh-api-connector artifact:

@VERSION@ should be replaced with the version you want to use.

Maven

<dependency>
    <groupId>help.swgoh.api</groupId>
    <artifactId>swgoh-api-connector</artifactId>
    <version>@VERSION@</version>
</dependency>

Gradle

compile 'help.swgoh.api:swgoh-api-connector:@VERSION@'

Examples

In code, use the SwgohAPIBuilder to initialize a new instance of the client:

SwgohAPI api = new SwgohAPIBuilder()
        .withUsername( "username" )
        .withPassword( "password" )
        .build();

Request for a player profile by ally code:

//single player
int allyCode = 123456789;
String player = api.getPlayer( allyCode ).get();

//multiple players
int allyCode = 123456789;
int otherAllyCode = 987654321;
List<Integer> allyCodes = Arrays.asList( allyCode, otherAllyCode );
String players = api.getPlayers( allyCodes ).get();

//only return certain fields in the response
int allyCode = 123456789;
String player = api.getPlayer( 
        allyCode,
        new SwgohAPIFilter( "name", "allyCode", "roster" )
).get();

Request guild info by ally code:

int allyCode = 123456789;
String guild = api.getGuild( allyCode ).get();

//only return certain fields in the response
int allyCode = 123456789;
String guild = api.getGuild( 
        allyCode,
        new SwgohAPIFilter( "name", "gp", "roster", "updated" )
).get();

Request various other kinds of data:

//no filtering, large response
String unitsJson = api.getSupportData( SwgohAPI.Collection.unitsList ).get();

//specify custom filtering criteria for a smaller response
Map<String, Object> matchCriteria = new HashMap<>();
matchCriteria.put( "baseId", "GREEDO" );
matchCriteria.put( "rarity", 7 );
String greedoJson = api.getSupportData( SwgohAPI.Collection.unitsList,
        matchCriteria,
        SwgohAPI.Language.English,
        new SwgohAPIFilter( "nameKey", "combatType", "descKey", "thumbnailName", "baseId" )
).get();

...and so much more! Please reference SwgohAPI.Collection for a list of all available data collections.

Global Discord Registry

(Patreon-tier API accounts only)

This API offers a Discord registry, which is simply a map of ally codes to Discord IDs.

This registry is shared among all Patreon-tier API accounts. If your users have already registered through a different tool that uses this registry, then their registration will already be available to you as well.

Registering an ally code more than once will cause that ally code's association to be overwritten. Registering a Discord ID more than once will cause that Discord ID to be linked to multiple ally codes. This allows users to link their Discord account to all of their game alts, but does not allow a game account to be tied to more than one Discord user at a time.

//create association
int allyCode = 123456789;
String discordId = "098765432123456789";
api.register( allyCode, discordId );

//get association
int allyCode = 123456789;
RegistrationResponse response = api.getRegistrationByAllyCode( allyCode ).get();
//or
String discordId = "098765432123456789";
RegistrationResponse response = api.getRegistrationByDiscordId( discordId ).get();

//remove association
int allyCode = 123456789;
api.unregisterAllyCode( allyCode );
//or
String discordId = "098765432123456789";
api.unregisterDiscordId( discordId );

In order to use this feature, your API account will need to upgrade to Patreon-tier.

You can do this by becoming a Patreon patron and supporting the API in any of the following ways:
API Development
Server Hosting

After becoming a patron, be sure to log into Discord and contact either Midgar777#0394 or shittybill#3024 and give them your API account username so that your account can be given access to this awesome feature.

Asynchronous API with CompletableFuture

Don't want to wait on a response from the API? Set up a callback method using the returned CompletableFuture.

int allyCode = 123456789;
api.getPlayer( allyCode ).thenAccept( player -> {
    //do something with player. This will happen in the future, leaving the main thread unblocked
});

Language Specification

To receive data in a supported language, simply pass the specified language into the overloaded method of your choice.

Example of language-specified result:

String jsonUnitsInKorean = api.getSupportData( SwgohAPI.Collection.unitsList, SwgohAPI.Language.Korean );

Spring Integration

If you'd like to see this work with Spring's dependency injection magic, simply write something similar to the following code:

@Configuration
public class SwgohConfiguration
{
    @Bean
    public SwgohAPI swgohApi()
    {
        return new SwgohAPIBuilder()
                .withUsername( "username" )
                .withPassword( "password" )
                .build();
    }
}

And it's as simple as that. Now you can @Autowire the API client to your heart's content.

@Service
public class SwgohService
{
    @Autowired
    private SwgohAPI swgohApi;
}

Available Language Clients

NodeJS:
https://github.com/r3volved/api-swgoh-help/tree/node

NPM:
https://www.npmjs.com/package/api-swgoh-help

Java:
https://github.com/j0rdanit0/api-swgoh-help

C#:
https://github.com/SdtBarbarossa/SWGOH-Help-Api-C-Sharp https://gist.github.com/dwcullop/9c6b7933fe23163e59b94da1997adee7

PHP:
https://github.com/r3volved/api-swgoh-help/tree/php
https://github.com/rayderua/swhelp-api-client

Google App Script:
https://github.com/Dragonsight91/api-swgoh-help
https://github.com/PopGoesTheWza/swgoh-help-api

Google Sheets:
https://docs.google.com/spreadsheets/d/1lxRBR4d9bWKWGmnhkjYiZ5EMkFogtaCR-qN22D_DGsw/edit?usp=copy

Python:
https://github.com/platzman/swgoh.help.python

Laravel:
https://github.com/matthillman/swgoh-help

api-swgoh-help's People

Contributors

Stargazers

Watchers

api-swgoh-help's Issues

Can't get images api to work

I'm trying to get the images api to work to download custom images of the characters from the help api, but get FileNotFound exceptions regardless of what characters I ask for, what options I give (rarity, level, zeta) or whether they are toons or ships.

I don't see any documentation on the image api at https://api.swgoh.help/swgoh so it is hard for me to tell what the requested url should be nor try it with just a curl command, so I'm unsure if the issue is with .help or with the wrapping api.

The error message is always of the form:

Caused by: java.io.FileNotFoundException: https://api.swgoh.help/image/char/DARTHTRAYA?level=85&gear=12&rarity=7

Below the simplest main I could come up with that demonstrates the issue. I'm using version 4.2.1 of the api, but it was failing with 4.1.0 as well.

Going back to 4.0.1 removes the ability to use the SwgohAPIFilter, but the relevant pieces don't work with that version either.

Going back to 3.2 removes the ToonImageRequestBuilder so I didn't test any further back than 4.0.0.

import java.awt.image.BufferedImage;
import java.util.HashMap;
import java.util.Map;

import help.swgoh.api.SwgohAPI;
import help.swgoh.api.SwgohAPIBuilder;
import help.swgoh.api.SwgohAPIFilter;
import help.swgoh.api.image.ShipImageRequestBuilder;
import help.swgoh.api.image.ToonImageRequestBuilder;

public class Test {

  public static void main(String[] args) throws Exception {
    SwgohAPI api = new SwgohAPIBuilder()
        .withUsername( "daker13" )
        .withPassword( "************" )
        .build();

    try {
      System.out.println("First get some character info to prove I've got the api setup correctly");
      int allyCode = 421838524;
      Map<String, Object> matchCriteria = new HashMap<>();
      matchCriteria.put( "baseId", "GREEDO" );
      matchCriteria.put( "rarity", 7 );
      String greedoJson = api.getSupportData( SwgohAPI.Collection.unitsList,
          matchCriteria,
          SwgohAPI.Language.English,
          new SwgohAPIFilter( "nameKey", "combatType", "descKey", "thumbnailName", "baseId" )
      ).get();
      System.out.println(greedoJson);
    } catch(Exception e) {
      e.printStackTrace();
    }

    System.out.println("Now try the image api using the example at https://github.com/j0rdanit0/api-swgoh-help");
    //raw bytes of an image
    String baseId = "DARTHTRAYA"; //a full list of baseIds can be obtained through the "unitsList" collection
    try {
      byte[] bytes = api.getImage(
          new ToonImageRequestBuilder(baseId)
              .withStars(7)
              .withLevel(85)
              .withGear(12)
              .build()
      ).get();
    } catch(Exception e) {
      e.printStackTrace();
    }

    System.out.println("try with the buffered image too just to show both aren't working");
    //image in the form of a BufferedImage
    try {
      baseId = "TIEREAPER"; //a full list of baseIds can be obtained through the "unitsList" collection
      BufferedImage image = api.getBufferedImage(
          new ShipImageRequestBuilder(baseId)
              .withLevel(50)
              .withStars(5)
              .addPilot("DEATHTROOPER", 85, 11, 7, null)
              .addPilot("SHORETROOPER", 75, 5, 5, null)
              .build()
      ).get();
    } catch(Exception e) {
      e.printStackTrace();
    }
  }
}

The output from running the above program is:

First get some character info to prove I've got the api setup correctly
[{"thumbnailName":"tex.charui_greedo","nameKey":"Greedo","combatType":1,"descKey":"Deadly Attacker that gains extra attacks from Critical Hits","baseId":"GREEDO"}]

Now try the image api using the example at https://github.com/j0rdanit0/api-swgoh-help
java.util.concurrent.ExecutionException: help.swgoh.api.exception.SwgohAPIException: Unable to complete request.
	at java.util.concurrent.CompletableFuture.reportGet(CompletableFuture.java:357)
	at java.util.concurrent.CompletableFuture.get(CompletableFuture.java:1895)
	at Test.main(Test.java:45)
Caused by: help.swgoh.api.exception.SwgohAPIException: Unable to complete request.
	at help.swgoh.api.SwgohAPIClient.lambda$getImage$0(SwgohAPIClient.java:544)
	at java.util.concurrent.CompletableFuture$AsyncSupply.run(CompletableFuture.java:1590)
	at java.util.concurrent.CompletableFuture$AsyncSupply.exec(CompletableFuture.java:1582)
	at java.util.concurrent.ForkJoinTask.doExec(ForkJoinTask.java:289)
	at java.util.concurrent.ForkJoinPool$WorkQueue.runTask(ForkJoinPool.java:1056)
	at java.util.concurrent.ForkJoinPool.runWorker(ForkJoinPool.java:1692)
	at java.util.concurrent.ForkJoinWorkerThread.run(ForkJoinWorkerThread.java:157)
Caused by: java.io.FileNotFoundException: https://api.swgoh.help/image/char/DARTHTRAYA?level=85&gear=12&rarity=7
	at sun.net.www.protocol.http.HttpURLConnection.getInputStream0(HttpURLConnection.java:1890)
	at sun.net.www.protocol.http.HttpURLConnection.getInputStream(HttpURLConnection.java:1492)
	at sun.net.www.protocol.https.HttpsURLConnectionImpl.getInputStream(HttpsURLConnectionImpl.java:263)
	at java.net.URL.openStream(URL.java:1045)
	at help.swgoh.api.SwgohAPIClient.getImage(SwgohAPIClient.java:643)
	at help.swgoh.api.SwgohAPIClient.lambda$getImage$0(SwgohAPIClient.java:532)
	... 6 more
try with the buffered image too just to show both aren't working
java.util.concurrent.ExecutionException: help.swgoh.api.exception.SwgohAPIException: Unable to complete request.
	at java.util.concurrent.CompletableFuture.reportGet(CompletableFuture.java:357)
	at java.util.concurrent.CompletableFuture.get(CompletableFuture.java:1895)
	at Test.main(Test.java:61)
Caused by: help.swgoh.api.exception.SwgohAPIException: Unable to complete request.
	at help.swgoh.api.SwgohAPIClient.lambda$getBufferedImage$1(SwgohAPIClient.java:570)
	at java.util.concurrent.CompletableFuture$AsyncSupply.run(CompletableFuture.java:1590)
	at java.util.concurrent.CompletableFuture$AsyncSupply.exec(CompletableFuture.java:1582)
	at java.util.concurrent.ForkJoinTask.doExec(ForkJoinTask.java:289)
	at java.util.concurrent.ForkJoinPool$WorkQueue.runTask(ForkJoinPool.java:1056)
	at java.util.concurrent.ForkJoinPool.runWorker(ForkJoinPool.java:1692)
	at java.util.concurrent.ForkJoinWorkerThread.run(ForkJoinWorkerThread.java:157)
Caused by: java.io.FileNotFoundException: https://api.swgoh.help/image/ship/TIEREAPER?pilots=DEATHTROOPER-7-85-11-null%7CSHORETROOPER-5-75-5-null&level=50&rarity=5
	at sun.net.www.protocol.http.HttpURLConnection.getInputStream0(HttpURLConnection.java:1890)
	at sun.net.www.protocol.http.HttpURLConnection.getInputStream(HttpURLConnection.java:1492)
	at sun.net.www.protocol.https.HttpsURLConnectionImpl.getInputStream(HttpsURLConnectionImpl.java:263)
	at java.net.URL.openStream(URL.java:1045)
	at help.swgoh.api.SwgohAPIClient.getBufferedImage(SwgohAPIClient.java:651)
	at help.swgoh.api.SwgohAPIClient.lambda$getBufferedImage$1(SwgohAPIClient.java:563)
	... 6 more

Process finished with exit code 0

If there is any additional data I can provide, please let me know.

Thanks,

Greg

Recommend Projects

j0rdanit0 / api-swgoh-help Goto Github PK