pokeapi-reactor

A non-blocking, reactive API client for PokeAPI with caching for Spring Boot projects.

Features

Simple, single entry point for all client operations.
Non-blocking HTTP operations and non-blocking caching.
Fully customizable caching. Supports Spring Boot's generic CacheManager for caching.
Caching and non-caching configurations.

Getting started

Project Configuration

Properties

You can (must) configure the location of the PokeAPI instance you want to use. Add the following property to your application.properties:

skaro.pokeapi.base-uri=https://pokeapi.co/api/v2/ #or the url of your own instance

Application Context

Import one of pokeapi-reactor's configurations as well as specify your own reactor.netty.http.client.HttpClient bean. Two configurations are available: caching and non-caching. Below is an example of a caching configuration which uses a flexible HttpClient tuned for high parallel throughput.

@Configuration
@Import(PokeApiReactorCachingConfiguration.class)
@EnableCaching
public class MyPokeApiReactorCachingConfiguration {
	@Bean
	public ConnectionProvider connectionProvider() {
	    return ConnectionProvider.builder("Auto refresh & no connection limit")
		    .maxIdleTime(Duration.ofSeconds(10))
		    .maxConnections(500)
		    .pendingAcquireMaxCount(-1)
		    .build();
	}

	@Bean
	public HttpClient httpClient(ConnectionProvider connectionProvider) {
		return HttpClient.create(connectionProvider)
                  .compress(true)
                  .resolver(DefaultAddressResolverGroup.INSTANCE);
	}
}

Or, if you'd rather not enable caching:

@Configuration
@Import(PokeApiReactorNonCachingConfiguration.class)
public class MyPokeApiReactorNonCachingConfiguration {
	@Bean
	public ConnectionProvider connectionProvider() { ... }
	
	@Bean
	public HttpClient httpClient(ConnectionProvider connectionProvider) { ... }
}

Both the PokeApiReactorCachingConfiguration and PokeApiReactorNonCachingConfiguration will register the appropriate PokeApiClient bean.

Fetching a resource

Inject the registered PokeApiClient into your class and request a resource.

@Autowired
private PokeApiClient pokeApiClient;

...

public void printPokemon() {
   pokeApiClient.getResource(Pokemon.class, "pikachu")
      .map(pokemon -> String.format("%s has %d forms", pokemon.getName(), pokemon.getForms().size()))
      .subscribe(System.out::println);
}

If you don't mind blocking, you can simply block for the resource.

public void printPokemon() {
   Pokemon pokemon = pokeApiClient.getResource(Pokemon.class, "pikachu").block();
   String pokemonInfo = String.format("%s has %d forms", pokemon.getName(), pokemon.getForms().size()));
   System.out.println(pokemonInfo);
}

Following a resource

Following links to other resources also has first-class support.

public void printPokemonForms() {
   pokeApiClient.getResource(Pokemon.class, "pikachu")
      .flatMapMany(pokemon -> pokeApiClient.followResources(pokemon::getForms, PokemonForm.class))
      .map(form -> String.format("Pikachu has a form called %s", form.getName()))
      .subscribe(System.out::println);
}

Again, with blocking:

public void printPokemonForms() {
   Pokemon pokemon = pokeApiClient.getResource(Pokemon.class, "pikachu").block();
   List<PokemonForm> forms = pokeApiClient.followResources(pokemon::getForms, PokemonForm.class)
      .collectList()
      .block();

   for(PokemonForm form : forms) {
      String formInfo = String.format("Pikachu has a form called %s", form.getName());
      System.out.println(formInfo);
   }
}

Maven Configuration

The latest release can be pulled from GitHub's Apache Maven repository. To pull from their repository, you must add your GitHub credentials to your settings.xml (located in ${user.home}/.m2/settings.xml). You can read GitHub's artical about how to do that. But for impatient programmer's, below is yet another guide to configure Maven to pull from GitHub that holds your hand a little more closely - I always appreciate it when people do that.

Generate a token

Generate a PAT (Personal Access Token) with the read:packages privilege.

Add <server> and <repository> tags in settings.xml

Configure Maven to authenticate when trying to pull from GitHub's Apache Maven repoistory. If you don't have a settings.xml, create it under your .m2 directory. It should look something like this.

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
                      http://maven.apache.org/xsd/settings-1.0.0.xsd">

  <activeProfiles>
    <activeProfile>github</activeProfile>
  </activeProfiles>

  <profiles>
    <profile>
      <id>github</id>
      <repositories>
        <repository>
          <id>central</id>
          <url>https://repo1.maven.org/maven2</url>
        </repository>
        <repository>
          <id>github-skaro-pokeapi-reactor</id>
          <url>https://maven.pkg.github.com/SirSkaro/pokeapi-reactor</url>
        </repository>
      </repositories>
    </profile>
  </profiles>

  <servers>
    <server>
      <id>github-skaro-pokeapi-reactor</id>
      <username>YOUR USERNAME</username>
      <password>YOUR TOKEN YOU JUST CREATED</password>
    </server>
  </servers>
</settings>

Daniel-online/pokeapi-reactor