Modified 2 files

docs/alpha.md

@@ -1,74 +1,73 @@
-## SpaceTraders v2.0.0-alpha Preview
+# Alpha Preview Guide
 
-Hello everyone and welcome to the SpaceTraders v2.0-alpha preview! We are excited to share progress with our supporters and hope you enjoy the new changes to the game.
+Hello everyone and welcome to the SpaceTraders v2.0.0-alpha preview! We are excited to share progress with our supporters and hope you enjoy the new changes to the game.
 
-We've re-thought some elements of the API from lessons learned with our v1.0 release, and hope you will enjoy some of the fleshed out ship mechanics, larger universe to explore, and new ideas that we are still  working on behind the scenes. We really want the 2.0 API to be beginner friendly and reliably stable for developers to build on top of.
+We've re-thought some elements of the API using lessons learned from the v1 release. We hope you will enjoy some of the fleshed out ship mechanics, larger universe to explore, and various new ideas that are still in the works.
 
-We appreciate all of the positive comments and feedback, and look forward to a second year of building SpaceTraders!
+Our goal continues to be to create a fun and beginner friendly API that developers can reliably build on top of. We appreciate all of the positive comments and feedback, and look forward to a second year of building SpaceTraders!
 
-## Overview of the Alpha / Beta / Public releases
+## Overview
 
-The alpha release will be a period of about a month where we fix any critical bugs and make significant changes to API endpoints if they are necessary. The alpha phase will be shared mostly with our supporters and some close members of the community, so please don't advertise the release too broadly.
+The alpha release will be a period of about a month where we fix any critical bugs and make any significant changes to API endpoints. The alpha phase will be shared mostly with our supporters and some close members of the community, so please don't advertise the release too broadly. Having said that, the alpha won't be a secret, so there is no harm if you want to share it directly with friends.
 
-Having said that, the alpha won't be a secret, so there is no harm if you want to share it directly with friends.
+Following the alpha will be a public beta release, at which point it should be relatively safe to build an SDK on top of the API. We'll continue to add new features, but we will be hesitant to make any significant breaking changes to existing endpoints. We expect the beta to be a few weeks as we confirm the API is scaling well and performance issues are addressed.
-
-Following the alpha will be a public beta release, at which point it should be relatively safe to build an SDK on top of the API. We'll continue to add a few new features, but will be hesitant to make any significant breaking changes. We expect the beta to be a few weeks as we confirm the API is scaling well and performance issues are addressed.
 
 Then we will finally update all of the documentation and website to point to the new 2.0 release.
 
-## Alpha Goals
+### Alpha Goals
 
 Our goals for the early alpha are to gather feedback so we can guarantee API stability for those that want to start building SDKs. Once we go into a beta release, we will be much less likely to change any specific endpoint, and after a full release we will strive to only make backwards-compatible changes.
 
-## What can you do
+### Feedback
 
-We're genuinely happy to just have people play with the API, and sharing any feedback or progress will be super motivating for us. If you want to help in a specific way, we're looking for the following feedback from the alpha release:
+We're genuinely happy to just have people play the game and try the API. Sharing your feedback or progress will be super motivating for us as we continue to work in our free time.
 
-- Find and report bugs or exploits in the game, such as the ability to trade cargo your ship doesn't contain
+If you want to help in a specific way, we're looking for the following feedback from the alpha release:
+
+- Find and report bugs or exploits in the game
 - Look for typos or errors in the game data, symbols, etc.
 - Let us know if performance is an issue for any of the endpoints
-- Tell us which endpoints are painful to use or game mechanics that are tedious / uninteresting\
+- Tell us which endpoints are painful to use or game mechanics that are tedious / uninteresting / not fun
-- Anything that you think will be difficult for us to add later without breaking how the API works
+- Anything you think will be difficult for us to add later without breaking how the API works
 
-Again the goal is to catch significant changes that need to be made before the beta release. Thanks for any time you are able to provide to test it out!
+Again the goal is to catch significant changes that need to be made before the beta release. We appreciate any time you can dedicate to test out the new API endpoints.
 
-## New V2 Alpha Terminology
+### New Terminology
 
 The 2.0 version of the API has been significantly reworked and introduces some new terminology. Before reviewing the new endpoints in the next section, it's worth reading through some of the new terms and what they mean.
 
 - **Account** - you can register an account (not required) with your email address and discord handle and it will persist across resets. We will eventually add registration to the website, but for now you can do it via API calls. You will also be able to register your patreon contribution for special in-game recognition.
 - **Agent** - when you start a new game, you register as an agent and choose a symbol (4-8 characters) as your call sign. All of your ships, credits, etc. exist under your agent entity, and you can only have one agent at a time under your account. You will be able to start a new game by retiring your agent and creating a new one.
 - **Sector** - a slice of the universe filled with systems of different types such as star systems, black holes, or nebulae.
-- **System** - a collection of waypoints orbiting around a central feature such as a star or black hole. Systems contain an array of waypoints on an x, y plane.
+- **System** - a collection of waypoints orbiting around a central feature such as a star. Systems contain an array of waypoints on an x, y plane.
 - **Waypoint** - a location within a system that you can travel to and interact with. Some common types of waypoints include planets, asteroid fields and jump gates.
-- **Ship** - your ships can navigate between waypoints and jump across systems. They consist of a frame, reactor, engine and various modules and mounts.
+- **Ship** - your ships can navigate between waypoints and jump across systems. A ship consists of a frame, reactor, engine, modules and mounts.
 - **Ship Frame** - the structure of a ship which determines the number of modules and mounts that can be installed.
 - **Ship Reactor** - the power module of the ship and limits the types of power-intensive modules and mounts that can be installed.
-- **Ship Engine** - the engine of your ship and determines how fast your ship travels when navigating at slow-than-light speeds.
+- **Ship Engine** - the engine of your ship and determines how fast your ship travels when navigating at slower-than-light speeds.
-- **Ship Module** - an internal module that can be added or removed from your ship. Common modules include cargo bays and passenger cabins.
+- **Ship Module** - an internal module that can be added or removed from your ship. Common modules include cargo bays, passenger cabins, and jump drives.
 - **Ship Mount** - an external mount that can be added or removed from your ship. Common mounts include mining lasers and sensor arrays.
-- **Fuel** - a resource that is consumed by your ship when navigating. You can refuel your ship, and one unit of the FUEL good adds 100 units to your fuel to your ship's tank.
+- **Ship Fuel** - a resource that is consumed by your ship when navigating. You can refuel your ship, and one unit of the FUEL trade good adds 100 units to your fuel to your ship's tank.
-- **Crew** - the staff that run your ship and keep it operating at peek performance. Crew can be recruited throughout the universe and will eventually be subject to changes in morale, which will impact how your ship performs. Ships which are understaffed will perform poorly such as longer cooldowns, slower navigation, and more damage to the ship while navigating.
+- **Ship Crew** - the staff that run your ship and keep it operating at peek performance. Crew can be recruited throughout the universe and will eventually be subject to changes in morale, which will impact how your ship performs. Ships which are understaffed will perform poorly such as longer cooldowns, slower navigation, and more damage to the ship while navigating.
-- **Drone** - drone ships are the simplest type of ship to automate. They don't require fuel or crew, but are quite slow and incapable of jumping between systems without access to a jump gate. Drones also wear down quickly over time and need to be repaired or replaced.
+- **Drone** - drone ships are the simplest type of ship to automate. They don't require fuel or crew, but are slower, wear down quickly, and are incapable of jumping between systems without access to a jump gate.
-- **Navigate** - slower-than-light travel between waypoints. Most ship actions will fail while your ship is in-transit between waypoints. Wait until your ship has arrived before attempting any actions.
+- **Navigate** - slower-than-light travel between waypoints. A ship will depart from a waypoint and arrive at a destination after a duration has passed.
-- **Jump** - faster than light travel between systems. Jumping requires a jump drive or jump gate, and is instantaneous but subject to a cooldown between jumps.
-- **Survey** - find specific yields or ORE and other materials at a waypoint. Surveys return a list of signatures for extraction. These signatures are time-sensitive and will eventually expire as they move out of reach of your ship.
-- **Extract** - executes an extraction at a waypoint such as an asteroid field using one of your ships. Fills your cargo with random yields from that waypoint, or you can pass a survey signature and generate more targeted yields.
-- **Yield** - the types and quantities of ores or gases that can be extracted from a waypoint.
-- **Scan** - generates a list of arriving or departing ships from a waypoint. Later in our roadmap, you will be able to interdict some of these ships.
-- **Chart** - most systems are unexplored and need to be charted for other agents to see the details of the system. Submitting the chart will allow other agents to see the query the system, but sometimes keeping a system's details secret can be advantageous.
-- **Cooldown** - actions such as jumping, scanning and extracting will put your ship on a cooldown for that action. You should wait until the number of seconds have passed on the cooldown before attempting the action again.
-- **Contract** - a set of terms that will remit payment on completion. Contracts are generated through factions, and might request your agent to procure goods of a certain type, or transport of goods to a location by a certain time.
-- **Delivery** - transfers goods from your ship's cargo bay into the contract.
 - **Orbit** - when your ship arrives at a waypoint, it will be in orbit. Your ship must be in orbit to execute certain actions such as a scan or extraction. You can transition your ship from docked to orbit.
 - **Dock** - you can dock your ship at a waypoint after navigating to it. You will be able to execute market trades, and other planet-side actions once you've docked at a waypoint.
-- **Jettison** - jettison cargo from your ship into space to make room for more valuable cargo or to speed up your ship while navigating
+- **Jump** - faster-than-light travel between systems. Jumping requires a jump drive or access to a jump gate. Jumps are instantaneous but subject to a cooldown between jumps.
-- **Trade** - all items in the universe have a unique Trade Symbol in all caps, such as IRON_ORE, NANOBOTS and REACTOR_FISSION_I
+- **Extraction** - mines ore at an asteroid field or siphons gases at various waypoint types and deposits cargo into your ship. Surveying can be used to target specific yield types from a waypoint.
-- **Market** - most populated waypoints have a market where you can buy and sell goods by Trade Symbol. Each market will have a list of imports, exports and commodities that they trade in. Commodities rarely trade at a profit, but running a trade route between an export and import will bring much higer profits. Markets evolve with player activity, prices will rise and fall with changes in trade quantity, and new imports or exports will be added and removed as the market grows.
+- **Survey** - analyze a waypoint for specific yields such as ore or hydrocarbons. The resulting surveys are time-sensitive and will eventually expire as they move out of reach of your ship.
-- **Tariff** - some factions charge a tariff, which is a flat tax added to each unit of a good traded.
+- **Scan** - analyze a waypoint, route or system for more details. We currently support scanning approaching or departing ships at a waypoint, and will later support more modes of scanning.
-- **Shipyards** - players can purchase ships at shipyards and later execute maintanence on a ship or install new modules and mounts.
+- **Chart** - most systems and waypoints are unexplored and will need to be charted by an agent before others will be able to query that location.
+- **Cooldown** - actions such as jumping, scanning and extracting will put your ship on a cooldown for that action. You should wait until the number of seconds have passed on the cooldown before attempting the action again.
+- **Contract** - contracts are generated through factions, and might request your agent to procure goods of a certain type, or transport goods to a location by a certain time, in return for payment.
+- **Delivery** - transfers goods from your ship's cargo bay into a contract.
+- **Jettison** - ejects cargo from your ship's hold
+- **Trade** - all goods in the universe have a unique trade symbol (in all caps), such as `IRON_ORE`, `NANOBOTS` or `REACTOR_FISSION_I`.
+- **Market** - most populated waypoints have a market where you can buy and sell goods. Each market will have a list of imports, exports and commodities that you can trade in. Markets evolve with player activity - prices will rise and fall with trades, and new imports or exports will be added as the market grows.
+- **Tariff** - a flat tax added to each unit of a good traded at a market
+- **Shipyards** - where agents can purchase ships, perform maintanence, or install new modules and mounts.
 
-## New API Endpoints
+### New API Endpoints
 
 Here is a list of the new endpoints for the terms above. For this alpha-preview, some of the parameters for an endpoint are not fully implemented, but we've included them here to give an indication of what will be supported.
 
@@ -158,7 +157,7 @@ Static game data can be queried and should be cached using the `/game/data` endp
 /game/data
 ```
 
-## Getting Started
+## Quick Start
 
 If you are ready to dive in, just hit the endpoint to register as a new agent. Don't worry too much about account creation right now - temporary accounts will be setup when creating a new agent. We will likely still be doing hard resets during the alpha.
 
@@ -168,7 +167,7 @@ https POST v2-0-0-alpha.spacetraders.io/agents symbol=YOUR_SYMBOL faction=COMMER
 
 When starting a new game, you'll have a command ship to fly around and a contract with the Commerce Republic that you can accept for some credits. Try completing the contract, or just fly around and begin trading and exploring. You can also purchase some low-upkeep drones to begin automating trade routes.
 
-## Alpha Roadmap
+## Roadmap
 
 We're still hard at work completing items we have envisioned for the alpha release. We're working on full API documentation in Spotlight Studio, seeding new types of ships and balancing stats, and so much more.
 

reference/SpaceTraders.yaml

@@ -1,19 +1,28 @@
 openapi: 3.1.0
 info:
   title: SpaceTraders API
-  version: '2.0.0-alpha'
+  version: 2.0.0-alpha
-  summary: Documentation for the SpaceTraders API
+  summary: SpaceTraders is a unique multiplayer game built on a free Web API.
   contact:
     name: Joel Brubaker
     email: joel@spacetraders.io
   license:
-    name: NONE
+    name: 'No'
   description: |-
-    SpaceTraders is a unique multiplayer game built on a free Web API. You control a fleets of ships that can explore the universe, mine asteroids, automate trade routes, meet new factions, and discover hidden technology. Put your algorithms to the test during one of our regular competitive seasons or build a client to share with the community.
+    SpaceTraders is a unique multiplayer game built on a free Web API. You control a fleets of ships that can explore the universe, mine asteroids, automate trade routes, meet new factions, and discover hidden technology.
 
-    SpaceTraders is a RESTful API and currently in an alpha stage of development. Join our Discord to learn more.
+    Participate in one of our regular competitive seasons or build a client to share with the community.
+
+    SpaceTraders is currently in an alpha stage of development. Join our Discord to learn more.
+
+    ```json http
+    {
+      "method": "GET",
+      "url": "https://v2-0-0.alpha.spacetraders.io/status",
+    }
+    ```
 servers:
-  - url: 'http://v2-0-0.alpha.spacetraders.io'
+  - url: 'https://v2-0-0.alpha.spacetraders.io'
     description: v2.0.0-alpha
 paths:
   /agents:
@@ -136,6 +145,8 @@ paths:
                       headquarters: X1-OE-PM
                       credits: 0
       operationId: get-my-agent
+      security:
+        - Agent Token: []
   '/my/ships/{shipSymbol}/chart':
     post:
       summary: Submit a system or waypoint chart
@@ -1222,6 +1233,7 @@ paths:
 components:
   schemas: {}
   securitySchemes:
-    API Key - 1:
+    Agent Token:
       type: http
       scheme: bearer
+      description: When you register a new agent you will be granted a private bearer token which grants authorization to use the API.