SpaceTraders.Client 0.1.4

SpaceTraders.Client

Developer-friendly & type-safe Csharp SDK specifically catered to leverage SpaceTraders.Client API.

<div align="left"> <a href="https://www.speakeasy.com/?utm_source=space-traders-client&utm_campaign=csharp"><img src="https://custom-icon-badges.demolab.com/badge/-Built%20By%20Speakeasy-212015?style=for-the-badge&logoColor=FBE331&logo=speakeasy&labelColor=545454" /></a> <a href="https://opensource.org/licenses/MIT"> <img src="https://img.shields.io/badge/License-MIT-blue.svg" style="width: 100px; height: 28px;" /> </a> </div>

<br /><br />

Summary

SpaceTraders API: SpaceTraders is an open-universe game and learning platform that offers a set of HTTP endpoints to control a fleet of ships and explore a multiplayer universe.

The API is documented using OpenAPI. You can send your first request right here in your browser to check the status of the game server.

{
  "method": "GET",
  "url": "https://api.spacetraders.io/v2",
}

Unlike a traditional game, SpaceTraders does not have a first-party client or app to play the game. Instead, you can use the API to build your own client, write a script to automate your ships, or try an app built by the community.

We have a Discord channel where you can share your projects, ask questions, and get help from other players.

Table of Contents

• SpaceTraders.Client
• Development
  • Maturity
  • Contributions

SDK Installation

To add a reference to a local instance of the SDK in a .NET project:

dotnet add reference src/SpaceTraders/Client/SpaceTraders.Client.csproj

SDK Example Usage

Example

using SpaceTraders.Client;
using SpaceTraders.Client.Models.Requests;

var sdk = new SpaceTradersClient();

var res = await sdk.Status.GetAsync(security: new GetStatusSecurity() {
    AgentToken = "<YOUR_BEARER_TOKEN_HERE>",
});

// handle response

Authentication

Per-Client Security Schemes

This SDK supports the following security scheme globally:

To authenticate with the API the AgentToken parameter must be set when initializing the SDK client instance. For example:

using SpaceTraders.Client;
using SpaceTraders.Client.Models.Components;
using SpaceTraders.Client.Models.Requests;

var sdk = new SpaceTradersClient(agentToken: "<YOUR_BEARER_TOKEN_HERE>");

RegisterRequest req = new RegisterRequest() {
    Faction = FactionSymbol.Quantum,
    Symbol = "BADGER",
};

var res = await sdk.Agents.RegisterAsync(req);

// handle response

Per-Operation Security Schemes

Some operations in this SDK require the security scheme to be specified at the request level. For example:

using SpaceTraders.Client;
using SpaceTraders.Client.Models.Requests;

var sdk = new SpaceTradersClient();

var res = await sdk.Status.GetAsync(security: new GetStatusSecurity() {
    AgentToken = "<YOUR_BEARER_TOKEN_HERE>",
});

// handle response

Available Resources and Operations

<details open> <summary>Available methods</summary>

Agents

• Register - Register New Agent
• Self - Get Agent
• Get - List Agents
• Public - Get Public Agent

Contracts

• List - List Contracts
• Get - Get Contract
• Accept - Accept Contract
• Deliver - Deliver Cargo to Contract
• Fulfill - Fulfill Contract

Factions

• All - List Factions
• Get - Get Faction

Fleet

• List - List Ships
• PurchaseShip - Purchase Ship
• GetShip - Get Ship
• GetCargo - Get Ship Cargo
• Orbit - Orbit Ship
• Refine - Ship Refine
• CreateChart - Create Chart
• GetCooldown - Get Ship Cooldown
• Dock - Dock Ship
• CreateSurvey - Create Survey
• Extract - Extract Resources
• Siphon - Siphon Resources
• ExtractResourceWithSurvey - Extract Resources with Survey
• Jettison - Jettison Cargo
• Jump - Jump Ship
• Navigate - Navigate Ship
• PatchShipNav - Patch Ship Nav
• GetNav - Get Ship Nav
• Warp - Warp Ship
• SellCargo - Sell Cargo
• ScanSystems - Scan Systems
• ScanWaypoints - Scan Waypoints
• ScanShips - Scan Ships
• Refuel - Refuel Ship
• PurchaseCargo - Purchase Cargo
• TransferCargo - Transfer Cargo
• NegotiateContract - Negotiate Contract
• GetMounts - Get Mounts
• InstallMount - Install Mount
• RemoveMount - Remove Mount
• GetScrapValue - Get Scrap Ship
• Scrap - Scrap Ship
• GetRepairCost - Get Repair Ship
• Repair - Repair Ship

Status

• Get - Get Status

Systems

• List - List Systems
• Get - Get System
• ListWaypoints - List Waypoints in System
• GetWaypoint - Get Waypoint
• GetMarket - Get Market
• GetShipyard - Get Shipyard
• GetJumpGate - Get Jump Gate
• GetConstruction - Get Construction Site
• SupplyConstruction - Supply Construction Site

</details>

Error Handling

Handling errors in this SDK should largely match your expectations. All operations return a response object or throw an exception.

By default, an API error will raise a SpaceTraders.Client.Models.Errors.APIException exception, which has the following properties:

When custom error responses are specified for an operation, the SDK may also throw their associated exceptions. You can refer to respective Errors tables in SDK docs for more details on possible exception types for each operation. For example, the GetAsync method throws the following exceptions:

Example

using SpaceTraders.Client;
using SpaceTraders.Client.Models.Errors;
using SpaceTraders.Client.Models.Requests;

var sdk = new SpaceTradersClient();

try
{
    var res = await sdk.Status.GetAsync(security: new GetStatusSecurity() {
        AgentToken = "<YOUR_BEARER_TOKEN_HERE>",
    });

    // handle response
}
catch (Exception ex)
{
    if (ex is SpaceTraders.Client.Models.Errors.APIException)
    {
        // Handle default exception
        throw;
    }
}

Server Selection

Override Server URL Per-Client

The default server can be overridden globally by passing a URL to the serverUrl: string optional parameter when initializing the SDK client instance. For example:

using SpaceTraders.Client;
using SpaceTraders.Client.Models.Requests;

var sdk = new SpaceTradersClient(serverUrl: "https://api.spacetraders.io/v2");

var res = await sdk.Status.GetAsync(security: new GetStatusSecurity() {
    AgentToken = "<YOUR_BEARER_TOKEN_HERE>",
});

// handle response

Development

Maturity

This SDK is in beta, and there may be breaking changes between versions without a major version update. Therefore, we recommend pinning usage to a specific package version. This way, you can install the same version each time without breaking changes unless you are intentionally looking for the latest version.

Contributions

While we value open-source contributions to this SDK, this library is generated programmatically. Any manual changes added to internal files will be overwritten on the next generation. We look forward to hearing your feedback. Feel free to open a PR or an issue with a proof of concept and we'll do our best to include it in a future release.

SDK Created by Speakeasy