Editing SimTX API v24/Server directory

{{SimTX API v24 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 v24/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 -H "Authorization: Bearer $SIMTX_TOKEN"
</syntaxhighlight>

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

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

{| class="wikitable"
! Field !! Type !! Description
|-
| <code>serverId</code> || string || Stable identifier. Used when requesting a [[SimTX API v24/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.
|}

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

== Semantics ==
* A server appears only while it is enabled and holds a live registration lease with the account service. The lease lasts 60 seconds and running servers keep renewing it, so a server that stops renewing it 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. The default port of the server software is 5100, but the public deployment currently listens on '''5556''', and operators may change it at any time.
* The directory may list several servers. Each is a separate simulated world; stations on one server cannot hear stations on another.

== Receiving without an account ==
The directory requires a credential, but [[SimTX API v24/Receiver session|receiving]] does not. A receive-only client without an account can let the user enter a host and port, or ship with the public address as a default (<code>argon.simtx.net:5556</code> at the time of writing) and treat it as configuration rather than a constant.

== 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 v24 navbox}}
[[Category:SimTX API v24]]
[[Category:SimTX API v24 account service]]