spacetradersapi / api-docs Goto Github PK

View Code? Open in Web Editor NEW

133.0 133.0 34.0 317 KB

The API documentation for the SpaceTraders API

JavaScript 100.00%

api-docs's People

Contributors

Stargazers

Watchers

api-docs's Issues

Document status endpoint

https://api.spacetraders.io/v2/ is undocumented.
While you are at it also consider streamlining Leaderboard entries as to use only one DTO for all leaderboards:

class Entry {
string $agentSymbol;
int $value;
}

The meaning of $value is derived and directly dependent on the leaderboard type, naming the $value differently for every leaderboard does not add information.

This simplifies leaderboard handling on client side as you can use generic code for everything but the headline.

agent details should include faction schema

To create an agent, one has to select a starting faction. Later on, when querying /my/agent the response does not contain agent faction data.

Why API blocks requests from Iran?

Error: Forbidden
Your client does not have permission to get URL /v2/ from this server.

[Once] 500 response from extract

This has only happened once so far, hopefully I gathered the right information to make it possible to find.

I sent this request:

POST /my/ships/BMAC-6/sell
Accept: application/json
Authorizations: Bearer <Token>
{"symbol":"AMMONIA_ICE","units":18}

And received this response:

{"error":{"code":500,"message":"Something unexpected went wrong! If you want to help you can file an issue here: https://github.com/SpaceTradersAPI/api-docs"}}

Response headers (I manually unescaped this JSON, hopefully I did it right):

[
{"Name":"access-control-allow-origin","Value":"*","Type":3},
{"Name":"access-control-expose-headers","Value":"Retry-After, X-RateLimit-Type, X-RateLimit-Limit-Burst, X-RateLimit-Limit-Per-Second, X-RateLimit-Remaining, X-RateLimit-Reset","Type":3},
{"Name":"retry-after","Value":"1","Type":3},
{"Name":"x-ratelimit-type","Value":"IP Address","Type":3},
{"Name":"x-ratelimit-limit-burst","Value":"10","Type":3},
{"Name":"x-ratelimit-limit-per-second","Value":"2","Type":3},
{"Name":"x-ratelimit-remaining","Value":"1","Type":3},
{"Name":"x-ratelimit-reset","Value":"2023-05-16T08:51:25.295Z","Type":3},
{"Name":"x-cloud-trace-context","Value":"8ab4f8988b29bccd8365e1b9c4df8e91","Type":3},
{"Name":"Alt-Svc","Value":"h3=\":443\"; ma=2592000,h3-29=\":443\"; ma=2592000","Type":3},
{"Name":"Content-Length","Value":"159","Type":3},
{"Name":"Content-Type","Value":"application/json; charset=utf-8","Type":3},
{"Name":"Date","Value":"Tue, 16 May 2023 08:51:38 GMT","Type":3},
{"Name":"ETag","Value":"W/\"9f-HbG5+JfqBJBz7L32C03zLiY3WS8\"","Type":3},
{"Name":"Server","Value":"Google Frontend","Type":3},
{"Name":"Via","Value":"1.1 google","Type":3},
{"Name":"X-Powered-By","Value":"Express","Type":3}
]

This was the prior state of the ship:

{"symbol":"BMAC-6","registration":{"role":"EXCAVATOR","name":"BMAC-6","factionSymbol":"ASTRO"},"nav":{"status":"DOCKED","flightMode":"CRUISE","systemSymbol":"X1-AC10","waypointSymbol":"X1-AC10-31755X","route":{"destination":{"type":"ASTEROID_FIELD","symbol":"X1-AC10-31755X","systemSymbol":"X1-AC10","x":-2,"y":-29},"departure":{"type":"MOON","symbol":"X1-AC10-73983X","systemSymbol":"X1-AC10","x":6,"y":-8},"departureTime":"2023-05-16T08:11:46.756Z","arrival":"2023-05-16T08:13:51.749Z"}},"crew":{"rotation":"STRICT","current":0,"required":0,"capacity":0,"morale":100,"wages":0},"frame":{"symbol":"FRAME_DRONE","name":"Frame Drone","description":"A small, unmanned spacecraft used for various tasks, such as surveillance, transportation, or combat.","condition":100,"moduleSlots":3,"mountingPoints":2,"fuelCapacity":100,"requirements":{"power":1,"crew":-3}},"reactor":{"symbol":"REACTOR_CHEMICAL_I","name":"Chemical Reactor I","description":"A basic chemical power reactor, used to generate electricity from chemical reactions.","condition":100,"powerOutput":15,"requirements":{"crew":3}},"engine":{"symbol":"ENGINE_IMPULSE_DRIVE_I","name":"Impulse Drive I","description":"A basic low-energy propulsion system that generates thrust for interplanetary travel.","condition":100,"speed":2.0,"requirements":{"power":1}},"modules":[{"symbol":"MODULE_CARGO_HOLD_I","capacity":30,"name":"Cargo Hold","description":"A module that increases a ship's cargo capacity.","requirements":{"power":1,"slots":1}},{"symbol":"MODULE_MINERAL_PROCESSOR_I","name":"Mineral Processor","description":"Crushes and processes extracted minerals and ores into their component parts, filters out impurities, and containerizes them into raw storage units.","requirements":{"power":1,"slots":2}}],"mounts":[{"symbol":"MOUNT_MINING_LASER_I","name":"Mining Laser I","description":"A basic mining laser that can be used to extract valuable minerals from asteroids and other space objects.","strength":10,"requirements":{"power":1}}],"cargo":{"capacity":30,"units":30,"inventory":[{"symbol":"AMMONIA_ICE","name":"Ammonia Ice","description":"A valuable substance used in the production of fertilizers and other chemical products.","units":18},{"symbol":"ALUMINUM_ORE","name":"Aluminum Ore","description":"A valuable ore used in the production of aluminum and other alloys. Aluminum ore is an essential component in the construction of ship hulls and other structural components.","units":4},{"symbol":"COPPER_ORE","name":"Copper Ore","description":"A valuable ore used in the production of copper and other alloys. Copper ore is an essential component in the production of electronic components and wiring.","units":4},{"symbol":"SILVER_ORE","name":"Silver Ore","description":"A raw, unprocessed form of silver, often found in mines and underground deposits on planets and moons.","units":4}]},"fuel":{"current":78,"capacity":100,"consumed":{"amount":22,"timestamp":"2023-05-16T08:11:46.749Z"}}}

The sale item was removed from the ship's cargo, but I didn't confirm whether the money was received.

Only a Single Sector

All systems are in the sector "X1".

Introduce multiple sectors?

[Feature Request ✨] Ability to filter systems by sector

It would be great to be able to query for systems within a particular sector, either through a query param like sector=X1 or as a separate endpoint like /v2/sectors and /v2/sectors/{sectorSymbol} where a sector returns an array of System symbols.

Shipyard endpoint not returning ships

The shipyard endpoint documentation states that extra fields are returned when a ship is at the waypoint but this doesn't seem to be the case, either when docked or in orbit. Is there something else I need to do in order to get the additional information?

[Feature Request ✨] Error message noting outdated token

tldr; reset is a feature not an HTTP error, should be treated like one

In requests that contain a Token, but are for invalid game versions, return a friendly error message letting users know their token is not valid post reset.

This would require encoding which version a token was generated for, and checking it against the current version of the game.

I think this would go a long way towards communicating the concept, and occurrence, of resets to players in a clear way. If it is it's own error code, then we can programmatically check too.

Current error message is:

{
  "error": {
    "message": "Token was invalid or could not be parsed: \"eyJhbGciOi...\"",
    "code": 4104
  }
}

I'm suggesting something like:

{
  "error": {
    "message": "Token is for previous version of the universe, please generate a new one : \"eyJhbGciOi...\"",
    "code": "SOME_OUTDATED_TOKEN_ERROR_CODE",
    "data": {
      "token": [
        "Token sent is for version XX, latest is YY, see YY changelog here https://spacetraders.io/changelog/YY"
      ]
    }
  }
}

500 when creating survey at X1-XA95-57213D

Times are in California time. Ship #1 is the command ship.

I was expecting something else to go wrong, but it looks like the command ship was trying to create a survey at X1-XA95-57213D?

🛸#1 🛫 to X1-XA95-57213D ASTEROID_FIELD (00:00:43) spent 85 fuel
[WARN] 🛸#4 All systems connected to X1-DS14-05264X explored, jumping to furthest system, X1-Y64.
🛸#4 🥶 for 00:03:05
[WARN] 🛸#5 All systems connected to X1-UD78-72865Z explored, jumping to furthest system, X1-KF4.
🛸#5 🥶 for 00:03:00
⏱️  32s until 2023-05-27 20:30:29.915
Unhandled exception:
ApiException 500: {"error":{"code":500,"message":"Something unexpected went wrong! If you want to help you can file an issue here: https://github.com/SpaceTradersAPI/api-docs"}}
#0      FleetApi.createSurvey (package:space_traders_api/api/fleet_api.dart:332:7)
<asynchronous suspension>
#1      loadOrCreateSurveySetIfPossible (package:space_traders_cli/behavior/miner.dart:27:20)
<asynchronous suspension>
#2      advanceMiner (package:space_traders_cli/behavior/miner.dart:88:21)
<asynchronous suspension>
#3      logicLoop (package:space_traders_cli/logic.dart:119:25)
<asynchronous suspension>
#4      logic (package:space_traders_cli/logic.dart:201:7)
<asynchronous suspension>
#5      main (file:///C:/Users/micro/Documents/GitHub/space_traders/packages/space_traders_cli/bin/space_traders_cli.dart:35:3)
<asynchronous suspension>

Rate limit response is sometimes different

I was trying to write a simple loop to fetch every page of systems using the List Systems endpoint, which takes a while. I get normal rate limit 429 responses for a while, and have my code wait for the time provided in the Retry-After header. But after a while (almost 150 pages), I get a different kind of rate limit response. It doesn't have a Retry-After header, and the response body isn't JSON, but what looks like HTML:

<!doctype html><meta charset="utf-8"><meta name=viewport content="width=device-width, initial-scale=1"><title>429</title>429 Too Many Requests

It almost looks like something else is rate limiting my requests, like a proxy or something.

Also, a bit off-topic, but is there a better way to fetch the full list of systems? Seems like the documented page size limit is only 20, but according to the docs there are 5,000 systems, which would be 250 pages, which takes quite a while with the rate-limiting. Maybe I shouldn't be fetching every single system? But then how can I do things like discover nearby systems?

API requires faction to create an agent, but factions api endpoint is gated by auth

To create an agent/account the request body requires an initial faction to be specified but the API endpoint to list factions is gated by auth.

500 while navigating to the waypoint

Got it a few minutes ago when navigating REASON_ANCE-1 ship towards waypoint X1-DC54-43853Z
Ship was on full fuel (1200 / 1200), in orbit of X1-DC54-89945X

Sadly since it happened in the strategy automation, don't have any extra info to add

Invalid Retry-After headers

I'm using the Space Traders API in Python with a client generated by openapi-generator. When I hit rate-limit errors, I get an error from the underlying urllib3 library used for the network handling:

urllib3.exceptions.InvalidHeader: Invalid Retry-After header: 0.493

According to MDN, the Retry-After header value must be either a date string or an integer number of seconds.

ShipyardTransaction.shipSymbol is confusing

ShipyardTransaction:

  /// The symbol of the ship that was the subject of the transaction.
  String shipSymbol;

it actually the tradeSymbol of the Ship you just bought, not it's new shipSymbol.

Where as MarketTransaction:

  /// The symbol of the ship that made the transaction.
  String shipSymbol;

And ShipModificationTransaction:

  /// The symbol of the ship that made the transaction.
  String shipSymbol;

It's just that it's called "shipSymbol" when actually being a TradeSymbol and the docs being ambiguous.

Missing initial asteroid field

So i've been following tutorial loosely while building my client, and choice VOID faction.

On the mining step, it mentions that i should navigate to asteroid field waypoint, but starting system has none.
I suppose only COSMIC faction has it guaranteed?

I think this would benefit a clarification of some sort

Starting system waypoints:

(None of the orbitals are asteroid fields either)

Missing instructions for getting the location in the quickstart

I was just trying out to get the location of my headquarters and the corresponding system and was stuck for quite a while on the "View your starting location" step.

It is not clear from the previous step that my "headquarters" response from /my/agent is a combined string from the system.
For example:

My "headquarters" string is B0-DT55-202001, which contains the system BO-DT55 and the waypoint 202001

I would suggest adding a hint in the quickstart that the headquarters response is a concatenated string and you have to separate it for the next query https://api.spacetraders.io/v2/systems/:systemSymbol/waypoints/:waypointSymbol

Waypoint filter incorrect spec

on /systems/{systemSymbol}/waypoints the spec reads as follows:

{
    "description": "Filter waypoints by one or more traits.",
    "in": "query",
    "name": "traits",
    "schema": {
        "oneOf": [
            {
                "$ref": "#/components/schemas/WaypointTrait"
            },
            {
                "type": "array",
                "items": {
                    "$ref": "#/components/schemas/WaypointTrait"
                }
            }
        ]
    }
}

however this means putting a #/components/schemas/WaypointTrait in the query path

but WaypointTrait is a type object! with 3 required properties: symbol, name, description

obviously this is not the intent of the spec

impact:

all generated code will use this endpoint incorrectly
generators for compiled languages (eg rust) may generate code that doesn't compile, making the library unusable

contract fulfillment endpoint is not documented

Contract fulfillment endpoint /my/contracts/{contractId}/fulfill is mentioned in agent creation docs but it is not explicitly mentioned in "contracts" section of the docs

Error when generating client library

I tried to generate a client library using the example from https://docs.spacetraders.io/api-guide/open-api-spec#generating-a-client-library

Specifically, this command:

openapi-generator generate \
 -i https://stoplight.io/api/v1/projects/spacetraders/spacetraders/nodes/reference/SpaceTraders.json?fromExportButton=true&snapshotType=http_service&deref=optimizedBundle \
 -o packages/spacetraders-sdk \
 -g typescript-axios \
 --additional-properties=npmName="spacetraders-sdk" \
 --additional-properties=npmVersion="2.0.0" \
 --additional-properties=supportsES6=true \
 --additional-properties=withSeparateModelsAndApi=true \
 --additional-properties=modelPackage="models" \
 --additional-properties=apiPackage="api"

And the resulting error:

Exception in thread "main" org.openapitools.codegen.SpecValidationException: There were issues with the specification. The option can be disabled via validateSpec (Maven/Gradle) or --skip-validate-spec (CLI).
 | Error count: 1, Warning count: 0
Errors:
	-attribute components.schemas.FactionSymbols.examples is unexpected

	at org.openapitools.codegen.config.CodegenConfigurator.toContext(CodegenConfigurator.java:668)
	at org.openapitools.codegen.config.CodegenConfigurator.toClientOptInput(CodegenConfigurator.java:695)
	at org.openapitools.codegen.cmd.Generate.execute(Generate.java:503)
	at org.openapitools.codegen.cmd.OpenApiGeneratorCommand.run(OpenApiGeneratorCommand.java:32)
	at org.openapitools.codegen.OpenAPIGenerator.main(OpenAPIGenerator.java:66)

This is possibly a duplicate of the issue reported in #69.

Missing error response schemas

The api docs don't contain any error response schemas, only successful responses.

I'm using a openapi generated typescript sdk which uses a generic ResponseError class for the errors

export declare class ResponseError extends Error {
    response: Response;
    name: "ResponseError";
    constructor(response: Response, msg?: string);
}

But this means i have to guess the schema like this

api.getMyShips()
  .then(response => console.log(response))
  .catch(async (err: ResponseError) => {
    const json = await err.response.json();
    console.error(err.message, json.error.code);
  });

Would be better if we had something like

api.getMyShips()
  .then(response => console.log(response))
  .catch((response: GetMyShips401Response) => console.log(response.error.message));

Just like GetMyShips200Response

export interface GetMyShips200Response {
    /**
     *
     * @type {Array<Ship>}
     * @memberof GetMyShips200Response
     */
    data: Array<Ship>;
    /**
     *
     * @type {Meta}
     * @memberof GetMyShips200Response
     */
    meta: Meta;
}

Docking throws a 500

The endpoint https://api.spacetraders.io/v2/my/ships/{shipSymbol}/dock returns

{
  "error": {
    "code":500,
    "message":"Something unexpected went wrong! If you want to help you can file an issue here: https://github.com/SpaceTradersAPI/issues-and-suggestions"
  }
}

Duplicate "markets" Tags

api-docs/reference/SpaceTraders.yaml

Line 2971 in 0305256

- name: markets

is a duplicate of

api-docs/reference/SpaceTraders.yaml

Line 2950 in 0305256

- name: markets

The second markets tag on line 2971 was introduced in commit b27949b. I would recommend removing one of them

Cheers,

No permission to use/access/something the api

In reference/SpaceTraders.json in the Info Object there is:

    "license": {
      "name": "No Permission",
      "url": "https://choosealicense.com/no-permission/"
    },

The OpenAPI spec seems real unclear on what a License Object means.

It seems to be saying either that there is no license to use the API
document (i.e. feeding it to the OpenAPI Generator would not be allowed) or
that access to the API (e.g. https://v2.api.spacetraders.io/) is not allowed.
Neither of these seems to fit with what the purpose of SpaceTraders.

Can we get the license object removed or change to something more open?

Perhaps MIT?

https://spdx.org/licenses/MIT.html

Status API resetDate description

According to docs resetDate is described as The date and time when the game server was last reset., however, it only contains the date.
resetDate is described the same but it's an instant instead of date and time.

Inconsistency in OpenAPI spec

Hello,

I noticed an inconsistency between 2 endpoints when generating an openapi client.
The endpoints in question are both POST request and require no body to be sent.
The first one:
/my/ships/{shipSymbol}/dock
Has no "requestBody" defined in the openAPI spec

However the second one:
"/my/ships/{shipSymbol}/negotiate/contract"

Requires an empty requestBody:
"requestBody": { "content": { "application/json": { "schema": {} } } }
https://github.com/SpaceTradersAPI/api-docs/blob/main/reference/SpaceTraders.json#L2770

Wouldn't it make more sense to remove the "requestBody" from the latter endpoint as well?

Stoplight mock server returns data out of schema

Attempting to use https://stoplight.io/mocks/spacetraders/spacetraders/96627693 to test my API implementation, but some of the data returned is not parse-able in general, and definitely not parse-able if I want to apply stricter parsing

https://spacetraders.stoplight.io/docs/spacetraders/86ed6bbe4f5d7-register-new-agent

      "agent": {
         "accountId": "string",
         "symbol": "string",
         "headquarters": "string",
         "credits": -9223372036854776000, <-- does not fit in an i64 (-9223372036854775808: int64 min)
         "startingFaction": "string",  <-- not one of the faction enum values
         "shipCount": 0
      },

I see a few other places that do not conform to enum standards, I haven't made it much futher then register at the moment since it is hard to write unit tests around.

refuel example uses v1 api url

Missed an fix from the old endpoint in quickstart.md:

https -A bearer -a $apiToken POST api.spacetraders.io/my/ships/$shipSymbol/refuel

Include arrival timestamp in ship currently in transit error response

The error response for a ship currently in transit (code 4214) doesn't include the arrival timestamp. This differs from the /navigate response format that only includes arrival.

It would be helpful to keep this response in line with both the /navigate response to make handling this delay consistent.

Example /navigate response:

{
    "data": {
        "nav": {
            "systemSymbol": "X1-DF55",
            "waypointSymbol": "X1-DF55-20250Z",
            "route": {
                "departure": {
                    "symbol": "X1-DF55-17335A",
                    "type": "ASTEROID_FIELD",
                    "systemSymbol": "X1-DF55",
                    "x": 30,
                    "y": -5
                },
                "destination": {
                    "symbol": "X1-DF55-20250Z",
                    "type": "PLANET",
                    "systemSymbol": "X1-DF55",
                    "x": -5,
                    "y": 9
                },
                "arrival": "2023-05-12T00:16:10.193Z",
                "departureTime": "2023-05-12T00:15:49.213Z"
            },
            "status": "IN_TRANSIT",
            "flightMode": "CRUISE"
        },
        "fuel": {
            "current": 1162,
            "capacity": 1200,
            "consumed": {
                "amount": 38,
                "timestamp": "2023-05-12T00:15:49.193Z"
            }
        }
    }
}

Current Error Response:

{
    "error": {
        "message": "Ship is currently in-transit from X1-ZA40-99095A to X1-ZA40-15970B and arrives in 86 seconds.",
        "code": 4214,
        "data": {
            "departureSymbol": "X1-ZA40-99095A",
            "destinationSymbol": "X1-ZA40-15970B",
            "secondsToArrival": 86
        }
    }
}

Suggested Error Response:

{
    "error": {
        "message": "Ship is currently in-transit from X1-ZA40-99095A to X1-ZA40-15970B and arrives in 86 seconds.",
        "code": 4214,
        "data": {
            "departureSymbol": "X1-ZA40-99095A",
            "destinationSymbol": "X1-ZA40-15970B",
            "secondsToArrival": 86,
            "arrival": "2023-05-14T22:06:59.979Z"
        }
    }
}

/my/ships/{shipSymbol}/scan/waypoints endpoint missing in SpaceTraders.json

The ship scan endpoint used in quickstart.md (https -A bearer -a $apiToken POST $apiUrl/my/ships/$shipSymbol/scan/waypoints) does not appear in the API doc SpaceTraders.json.

On the v2.api running server there is an enpoint at /my/ships/{shipSymbol}/scan/systems that does return data and start a cooldown on the ship, so it does seem to exist.

Please update SpaceTraders.json with information on that endpoint.

First contract is too hard?

This is more of a game balance question, sorry if this isn't the right place for those.

My very first contract that I got when creating my first account seems to require a whopping 13,700 aluminum ore, and I was only given three days to complete it. Since it's my first time playing I've already spent a couple days just getting my script going, and have just now gotten a basic mining loop working with about a day remaining. The basic mining ship I bought only has a cargo space of 30 and extracts like 10 ore at a time.

Is there a bug with the contract terms? It seems like this is way too much to deliver for the very first contract.

Better Dynamic Respone Generation

Link
So stoplight supports faker, which is immensely useful when writing sanity testing my sdk, as I can do it without having to go through the mess of setting up a secret for CI/CD or worrying about not being able to perform an action because I don't have the actual capability. However, I am unable to test waypoint symbols because, well, I parse them. So it would be cool if the dynamic response generation for waypoints could be either locked to a singular waypoint or set to a random list of them.

Old agent symbol length in /register description

/register description still has "The agent symbol is a 4-8 character string" after commit c84602e.

"Getting Started" kinda unclear about how to buy ship

I am currently going through https://docs.spacetraders.io/quickstart/purchase-ship

it states

Look for a waypoint with the SHIPYARD trait. [...] Take note of the symbol for the orbital station waypoint that has a shipyard, which you can use to purchase a mining drone.
To view the ships available for purchase at a shipyard, send the following request. You will notice that there is a mining drone available for purchase, which can help you fulfill your starting contract.

so my expectation is

find all waypoint with shipyards
find one of type "orbital"
list ship types
ship types MUST contain one of type "mining drone"

from what I observed, this isn't necessarily true, sometimes the "mining drone" isn't available in the "orbital" but e.g. "moon"

curl 'https://api.spacetraders.io/v2/systems/X1-RA81/waypoints?traits=SHIPYARD'
--header 'Authorization: Bearer eyJhbGci[...]

[...] "systemSymbol":"X1-RA81", "symbol":"X1-RA81-H59", "type":"MOON", [...]

curl 'https://api.spacetraders.io/v2/systems/X1-RA81/waypoints/X1-RA81-H59/shipyard'
--header 'Authorization: Bearer eyJhbG[...]

[...] "data":{"symbol":"X1-RA81-H59", "shipTypes":[{"type": "SHIP_SURVEYOR"}, {"type": "SHIP_MINING_DRONE" [...]

is it intended that any of the shipyards may contain the "mining drone", and if yes, could you please update the "getting started" to make that more clear?

Can not build API in GO using https://github.com/deepmap/oapi-codegen

I am attempting to play with the API using golang, however trying to build types and the client are failing using oapi-codegen.

deepmap/oapi-codegen#1045

It seems oapi-codegen requires fairly extensive mapping to be done for $ref's, and it does not like relative paths at all. I am posting this issue here in case anyone else in the community has managed to build the API for golang (either with oapi-codegen or some other tool) and can help me get started.

Otherwise, I'll have to resign myself to manually building a client API in go.

Thanks for any suggestions, thoughts, or ideas you might have in advance.

500 from negotiateContract

Unhandled exception:
ApiException 500: {"error":{"code":500,"message":"Something unexpected went wrong! If you want to help you can file an issue here: https://github.com/SpaceTradersAPI/api-docs"}}
#0      FleetApi.negotiateContract (package:openapi/api/fleet_api.dart:1261:7)
<asynchronous suspension>
#1      negotiateContractAndLog (package:cli/net/actions.dart:387:20)
<asynchronous suspension>
#2      acceptContractsIfNeeded (package:cli/behavior/trader.dart:423:5)
<asynchronous suspension>
#3      advanceTrader (package:cli/behavior/trader.dart:509:5)
<asynchronous suspension>
#4      advanceShips (package:cli/logic.dart:36:25)
<asynchronous suspension>
#5      logic (package:cli/logic.dart:124:7)
<asynchronous suspension>
#6      cliMain (file:///root/space_traders/packages/cli/bin/cli.dart:79:3)
<asynchronous suspension>
#7      main.<anonymous closure> (file:///root/space_traders/packages/cli/bin/cli.dart:85:7)
<asynchronous suspension>
#8      main (file:///root/space_traders/packages/cli/bin/cli.dart:83:3)

I don't have an exact time, but it was probably a minute or so after 2023-07-17 23:55:07.243 UTC.

Refining throws 500 errors

Upon trying to refine a single unit of PLATINUM, the following two responses were seen:

{
  "error": {
    "code": 500,
    "message": "Something unexpected went wrong! If you want to help you can file an issue here: https://github.com/SpaceTradersAPI/issues-and-suggestions"
  }
}

{
  "error": {
    "message": "Failed to update ship cargo. Ship (redacted) cargo does not contain 3 unit(s) of PLATINUM_ORE. Ship has 1 unit(s) of PLATINUM_ORE.",
    "code": 4219,
    "data": {
      "shipSymbol": (redacted),
      "tradeSymbol": "PLATINUM_ORE",
      "cargoUnits": 1,
      "unitsToRemove": 3
    }
  }
}

The ship in question has plenty of empty cargo space.

Despite the 500 error, the cooldown seems to be triggered nevertheless:

{
  "error": {
    "message": "Ship action is still on cooldown for 24 second(s).",
    "code": 4000,
    "data": {
      "cooldown": {
        "shipSymbol": "(redacted)",
        "totalSeconds": 180,
        "remainingSeconds": 24,
        "expiration": "2023-05-12T13:24:31.213Z"
      }
    }
  }
}

Invalid required field name for ShipRegistration

In the definition of ShipRegistration, the list of required members includes faction which is not a defined member. It probably should be factionSymbol. As a result, validating OpenAPI clients cannot even register since the response is invalid.

500 response on survey at X1-DN76-32104E

Happened several times in a row just now.

Unhandled exception:
ApiException 500: {"error":{"code":500,"message":"Something unexpected went wrong! If you want to help you can file an issue here: https://github.com/SpaceTradersAPI/api-docs"}}
#0      FleetApi.createSurvey (package:space_traders_api/api/fleet_api.dart:332:7)
ESEIDEL-1D - Orbiting X1-DN76-32104E ASTEROID_FIELD EXCAVATOR 0/60
Making request to /my/ships/ESEIDEL-1D/survey

The Dock & Orbit endpoints differ in response format

Not sure if this applies to other endpoints as well but noticing it with docking and orbiting.

When I request /my/agent I get back { data: { /* agent details */ } }, when I request /my/ships I get back { data: [ /* ships */ ] }, and so on. However when I request /my/ships/<id>/dock I get back { data: { nav: { /* nav details */ } } and same for /my/ships/<id>/dock. I think it'd be more consistent to return { data: { /* nav details */ } }.

ShipRefineResponse - tradeSymbol vs Symbol Mismatch

Similar to the other issue I just opened - seems there is another slight mismatch between the docs and what the API is returning.
Per the OpenAPI spec, for a refine request, produced and consumed are supposed to return "tradeSymbol" along with respective units.

However, it seems that the API is returning "symbol" for these produced and consumed values - leading to a situation where the model de-serialization fails (model expecting tradeSymbol, but data contains symbol) so my return values look like this:

produced=[ShipRefine201ResponseDataProducedInner(trade_symbol=None, units=10)] consumed=[ShipRefine201ResponseDataProducedInner(trade_symbol=None, units=30)]

Waypoint/SystemWaypoint schema inconsistency

Get System endpoint https://api.spacetraders.io/v2 /systems/{systemSymbol} response includes a waypoints object which is a list of Waypoint.

However, Get Waypoint endpoint https://api.spacetraders.io/v2 /systems/{systemSymbol}/waypoints/{waypointSymbol} returns a more detailed waypoint with more parameters. Why?
Why not return a detailed Waypoint in both endpoints?

I mean client could define two classes one named Waypoint with more detailed information and another compact called SystemWaypoint but they are fundamentally the same entity so it's better to treat them as such.

Error 500 gives a link to a deprecated repository

When I encountered an error 500, it returned the following message:

{
  "error": {
    "code":500,
    "message":"Something unexpected went wrong! If you want to help you can file an issue here: https://github.com/SpaceTradersAPI/issues-and-suggestions"
  }
}

However that repository mentions it's deprecated and issues should be filed here instead.

ShipRefineResponse Response Code Mismatch

I'm seeing an issue where the OpenAPI spec shows a 200 expected response for a Ship Refine action, but the API is actually returning a 201. I feel that the API is correct in returning a 201(since something is being created) and that the spec should be updated to match.

Discord invite on homepage invalid/expired

The Discord invite link doesn't seem to work anymore as it returns an error message.

Market Transaction minimums incorrect in OpenAPI Spec

Issue: Marketplaces can have transactions where values do not conform to the required minimums stated in OpenAPI spec. An example provided in the Discord by a fellow user:


{'waypointSymbol': 'X1-VS75-67965Z',
    'shipSymbol': 'SP4CE-ADMIR4L-3',
    'tradeSymbol': 'FUEL',
    'type': <Type1.PURCHASE: 'PURCHASE'>,
    'units': 0,
    'pricePerUnit': 252,
    'totalPrice': 0,
    'timestamp': datetime.datetime(2023, 5, 21, 10, 31, 18, 972000, tzinfo=datetime.timezone.utc)}

Proposed fix: Units & TotalPrice minimum values in models/MarketTransaction.json should be updated to 0?

Interestingly enough, minimums for similar properties in models/MarketTradeGood.json are set to 0:


    "purchasePrice": {
      "type": "integer",
      "description": "The price at which this good can be purchased from the market.",
      "minimum": 0
    },
    "sellPrice": {
      "type": "integer",
      "description": "The price at which this good can be sold to the market.",
      "minimum": 0
    }

500 from /extract

response says file an issue to help so I am filing an issue :)

POST to https://api.spacetraders.io/v2/my/ships/SIKAYN-D/extract

relevant section of my logging (filtered to show the http components) timestamps should be in UTC


2023-08-22 04:38:21 DEBUG    httpcore.connection[_trace.py:85](atrace) connect_tcp.started host='api.spacetraders.io' port=443 local_address=None timeout=5.0 socket_options=None
2023-08-22 04:38:21 DEBUG    httpcore.connection[_trace.py:85](atrace) connect_tcp.complete return_value=<httpcore._backends.anyio.AnyIOStream object at 0x7ff7913b94d0>
2023-08-22 04:38:21 DEBUG    httpcore.connection[_trace.py:85](atrace) start_tls.started ssl_context=<ssl.SSLContext object at 0x7ff793707bf0> server_hostname='api.spacetraders.io' timeout=5.0
2023-08-22 04:38:21 DEBUG    httpcore.connection[_trace.py:85](atrace) start_tls.complete return_value=<httpcore._backends.anyio.AnyIOStream object at 0x7ff7913b8210>
2023-08-22 04:38:21 DEBUG    httpcore.http11[_trace.py:85](atrace) send_request_headers.started request=<Request [b'POST']>
2023-08-22 04:38:21 DEBUG    httpcore.http11[_trace.py:85](atrace) send_request_headers.complete
2023-08-22 04:38:21 DEBUG    httpcore.http11[_trace.py:85](atrace) send_request_body.started request=<Request [b'POST']>
2023-08-22 04:38:21 DEBUG    httpcore.http11[_trace.py:85](atrace) send_request_body.complete
2023-08-22 04:38:21 DEBUG    httpcore.http11[_trace.py:85](atrace) receive_response_headers.started request=<Request [b'POST']>
2023-08-22 04:38:24 DEBUG    httpcore.http11[_trace.py:85](atrace) receive_response_headers.complete return_value=(b'HTTP/1.1', 500, b'Internal Server Error', [(b'x-powered-by', b'Express'), (b'access-control-allow-origin', b'*'), (b'access-control-expose-headers', b'Retry-After, X-RateLimit-Type, X-RateLimit-Limit-Burst, X-RateLimit-Limit-Per-Second, X-RateLimit-Remaining, X-RateLimit-Reset'), (b'retry-after', b'1'), (b'x-ratelimit-type', b'IP Address'), (b'x-ratelimit-limit-burst', b'10'), (b'x-ratelimit-limit-per-second', b'2'), (b'x-ratelimit-remaining', b'1'), (b'x-ratelimit-reset', b'2023-08-22T04:38:23.003Z'), (b'content-type', b'application/json; charset=utf-8'), (b'etag', b'W/"9f-HbG5+JfqBJBz7L32C03zLiY3WS8"'), (b'x-cloud-trace-context', b'5329f75db7d6bc059365a45e72221cf1'), (b'date', b'Tue, 22 Aug 2023 04:38:24 GMT'), (b'server', b'Google Frontend'), (b'Content-Length', b'159'), (b'via', b'1.1 google, 1.1 google'), (b'Alt-Svc', b'h3=":443"; ma=2592000,h3-29=":443"; ma=2592000')])
2023-08-22 04:38:24 INFO     httpx[_client.py:1729](_send_single_request) HTTP Request: POST https://api.spacetraders.io/v2/my/ships/SIKAYN-D/extract "HTTP/1.1 500 Internal Server Error"
2023-08-22 04:38:24 DEBUG    httpcore.http11[_trace.py:85](atrace) receive_response_body.started request=<Request [b'POST']>
2023-08-22 04:38:24 DEBUG    httpcore.http11[_trace.py:85](atrace) receive_response_body.complete
2023-08-22 04:38:24 DEBUG    httpcore.http11[_trace.py:85](atrace) response_closed.started
2023-08-22 04:38:24 DEBUG    httpcore.http11[_trace.py:85](atrace) response_closed.complete
2023-08-22 04:38:24 DEBUG    SpaceTrader[client.py:112](_post) b'{"error":{"code":500,"message":"Something unexpected went wrong! If you want to help you can file an issue here: https://github.com/SpaceTradersAPI/api-docs"}}'

quickstart waypoint scan error

From /register with faction=VOID the ship I started with was "nav" { "status": "DOCKED" }
which caused the example $apiUrl/my/ships/$shipSymbol/scan/waypoints to fail like so:

{
    "error": {
        "code": 4236,
        "data": {
            "waypointSymbol": "X1-UK8-56510E"
        },
        "message": "Ship action failed. Ship is not currently in orbit at X1-UK8-56510E."
    }
}

I can see two options:

Update quickstart to have an /orbit call
Create command ships already in orbit

Fails to build with openapi-core

Install with python:

pip install openapi-core==0.18.0

Example code:

with open(file, "r") as f:
    spec = Spec.from_file(f)

File "/home/.venv/lib/python3.11/site-packages/openapi_core/spec/paths.py", line 27, in from_dict
    validator.validate(data, base_uri=base_uri, spec_url=spec_url)
  File "/home/.venv/lib/python3.11/site-packages/openapi_spec_validator/validation/proxies.py", line 34, in validate
    raise err
openapi_spec_validator.validation.exceptions.OpenAPIValidationError: {'type': 'string', 'description': 'The symbol of the faction.', 'minLength': 1, 'enum': ['COSMIC', 'VOID', 'GALACTIC', 'QUANTUM', 'DOMINION', 'ASTRO', 'CORSAIRS', 'OBSIDIAN', 'AEGIS', 'UNITED', 'SOLITARY', 'COBALT', 'OMEGA', 'ECHO', 'LORDS', 'CULT', 'ANCIENTS', 'SHADOW', 'ETHEREAL'], 'examples': ['COSMIC']} is not valid under any of the given schemas

Failed validating 'oneOf' in schema['properties']['components']['properties']['schemas']['patternProperties']['^[a-zA-Z0-9\\.\\-_]+$']:
    {'oneOf': [{'$ref': '#/definitions/Schema'},
               {'$ref': '#/definitions/Reference'}]}

On instance['components']['schemas']['FactionSymbols']:
    {'description': 'The symbol of the faction.',
     'enum': ['COSMIC',
              'VOID',
              'GALACTIC',
              'QUANTUM',
              'DOMINION',
              'ASTRO',
              'CORSAIRS',
              'OBSIDIAN',
              'AEGIS',
              'UNITED',
              'SOLITARY',
              'COBALT',
              'OMEGA',
              'ECHO',
              'LORDS',
              'CULT',
              'ANCIENTS',
              'SHADOW',
              'ETHEREAL'],
     'examples': ['COSMIC'],
     'minLength': 1,
     'type': 'string'}

/game/loans missing from SpaceTraders.json

potential refactor in a section on how to generate a client library

if somebody would like to skip API client generation step and hop straight to game client development, more explicit step on how to generate an API client may be useful:

visit https://spacetraders.stoplight.io/docs/spacetraders
head to SpaceTraders API, on the top right side Export -> Bundled references(!). copy resulting URL
run curl -X GET "http://api.openapi-generator.tech/api/gen/servers" -H "Accept: */*", pick whatever language/framework you need
run curl -X POST -H "content-type:application/json" -d '{"openAPIUrl":"LINK_TO_BUNDLED_JSON"}' http://api.openapi-generator.tech/api/gen/servers/FRAMEWORK
download package from the link provided to curl request

NOTE:
if you want to try it with JS/TS or other languages potentially not supported by OpenAPI generator, copy JSON content from step 2, paste it into https://editor-next.swagger.io/ and select Generate Client option in the top menu.

spacetradersapi / api-docs Goto Github PK

api-docs's People

Contributors

Stargazers

Watchers

Forkers

api-docs's Issues

tldr; reset is a feature not an HTTP error, should be treated like one

Recommend Projects

Recommend Topics

Recommend Org