Java client

Java client for STAPI is the only client maintainted in STAPI's repository.

Client can be grabbed from Maven Central.

Create client

After adding client library to a project, it can be instatiated:

StapiRestClient stapiRestClient = new StapiRestClient(); // null when there is no need to change base URL

Or, if you're running a local Docker container, on port 8686 for example, use:

StapiRestClient stapiRestClient = new StapiRestClient("http://localhost:8686/");

Basic concepts

For every entity, there are two types of objects that can be used to query API. Let's use spacecraft as an example:

You can do:

stapiRestClient.getSpacecraftApi();

This will get you all low level operations that spacecraft endpoint offers. However, this is code generated by the prefered way is to write:

stapiRestClient.getSpacecraft();

This will return a simplified wrapper around the generated code.

Getting a list of entities

Every entity has two distinct operations, one for getting list or results, and one for getting single result.

Given that you execute a query for list of spacecrafts:

Spacecraft spacecraft = stapiRestClient.getSpacecraft();
// in criteria classes, page number, page size, and sort can always be set
// additionally, all search params for the given end can also be set
SpacecraftV2SearchCriteria spacecraftV2SearchCriteria = new SpacecraftV2SearchCriteria();
spacecraftV2SearchCriteria.setName("USS");
// searches for all spacecrafts with "USS" in the name, likely to find a lot of Federation starships
SpacecraftV2BaseResponse spacecraftV2BaseResponse = spacecraft.searchV2(spacecraftV2SearchCriteria);
 // this will contain first page of results
List<SpacecraftV2Base> spacecrafts = spacecraftV2BaseResponse.getSpacecrafts();
 // this will contain data about returned page, including whether there are more pages
ResponsePage page = spacecraftV2BaseResponse.getPage();

If you want to query all results from a particular endpoint, be aware of the conditions on which to continue querying, and conditions on which to stop, so you have all the results you need, but you're not inside a loop. The best way would be to increment page parameter (starting at 0), while also looking at lastPage becoming true, which means there are no more results.

Getting a single entity

Once the list of spacecrafts has been queried, a single spacecraft can be grabbed using a previously saved UID. For example, UID for NCC-1701-D is SRMA0000103444:

Spacecraft spacecraft = stapiRestClient.getSpacecraft();
SpacecraftV2FullResponse spacecraftV2FullResponse = spacecraft.getV2("SRMA0000103444");
 // this get's full spacecraft data; note that this field could be null, if spacecraft is not found by UID
spacecraftV2FullResponse.getSpacecraft();

The same concept applies to all other entities.

See also

• Versioning – understand difference between versions of endpoints, client and data