Editing SimTX API/Server directory

{{SimTX API navigation}}
The '''server directory''' lists the SimTX game servers that are currently online, with the host name and TCP port a client should connect to. It is the starting point for every [[SimTX API/Connection and handshake|game connection]].

== Request ==
<code>GET /api/v1/servers</code>

Requires a bearer credential (an access credential or a personal credential). Any scope is sufficient. Rate limit: 120 requests per minute per IP address.

<syntaxhighlight lang="bash">
curl -s 'https://auth.simtx.net/api/v1/servers?include=features' -H "Authorization: Bearer $SIMTX_TOKEN"
</syntaxhighlight>

{| class="wikitable"
! Parameter !! Description
|-
| <code>include</code> || Optional, comma-separated extras. <code>features</code> adds a <code>features</code> array to each entry.
|}

== Response ==
<code>200 OK</code>:

<syntaxhighlight lang="json">
{
  "servers": [
    {
      "serverId": "argon",
      "displayName": "Argon",
      "host": "argon.simtx.net",
      "port": 5556,
      "description": "Main public server",
      "features": ["stations.v1", "pointing", "ephemeris", "passes", "kinematics"]
    }
  ]
}
</syntaxhighlight>

{| class="wikitable"
! Field !! Type !! Description
|-
| <code>serverId</code> || string || Stable identifier. Used when requesting a [[SimTX API/Game tickets|game ticket]].
|-
| <code>displayName</code> || string || Name to show to users.
|-
| <code>host</code> || string || DNS name to connect to. Also the name to verify the server's TLS certificate against.
|-
| <code>port</code> || integer || TCP port of the game protocol.
|-
| <code>description</code> || string || Free text set by the operator. May be empty.
|-
| <code>features</code> || array of string || Only with <code>include=features</code>. The [[SimTX API/Compatibility and versioning#Feature registry|features]] the server advertises. Ignore names you do not know.
|}

Entries are sorted by display name, then by server ID.

== Semantics ==
* A server that goes offline disappears from the list within about a minute.
* An empty <code>servers</code> array means that no server is online. It is not an error.
* Always connect to the <code>host</code> and <code>port</code> from the directory. <code>argon.simtx.net</code> listens on '''5556'''.
* The directory may list several servers. Each is a separate simulated world; sessions on one server cannot hear sessions on another. Persistent [[SimTX API/Stations|stations]] belong to the account, not to a server, and can be used on any server that supports them.
* A server needs the feature <code>stations.v1</code> before the account service mints a station-bound [[SimTX API/Game tickets|ticket]] for it. The same list is in the game server's [[SimTX API/Packets/ServerHello|ServerHello]] after connecting.

== Receiving without an account ==
The directory requires a credential, but [[SimTX API/Receiver session|receiving]] does not. An ad-hoc receive-only client without an account can let the user enter a host and port, or ship with <code>argon.simtx.net:5556</code> as a configurable default.

== Errors ==
{| class="wikitable"
! HTTP !! <code>code</code> !! Meaning
|-
| 401 || <code>credential_missing</code> || No bearer credential was sent.
|-
| 401 || <code>credential_invalid</code> || The credential is invalid or expired.
|-
| 429 || <code>rate_limited</code> || Too many requests this minute.
|}

{{SimTX API navbox}}
[[Category:SimTX API]]
[[Category:SimTX API account service]]