refactor progress
This commit is contained in:
Hampus Kraft
764
fluxer_docs/relay-api/openapi.json
Normal file
764
fluxer_docs/relay-api/openapi.json
Normal file
@@ -0,0 +1,764 @@
|
||||
{
|
||||
"openapi": "3.1.0",
|
||||
"info": {
|
||||
"title": "Fluxer Relay Directory API",
|
||||
"version": "1.0.0",
|
||||
"description": "API for discovering and managing Fluxer relay servers for federation. The relay directory service maintains a registry of available relay servers that clients can use to connect to Fluxer instances through encrypted tunnels.",
|
||||
"contact": {
|
||||
"name": "Fluxer Developers",
|
||||
"email": "developers@fluxer.app"
|
||||
},
|
||||
"license": {
|
||||
"name": "AGPL-3.0",
|
||||
"url": "https://www.gnu.org/licenses/agpl-3.0.html"
|
||||
}
|
||||
},
|
||||
"servers": [
|
||||
{
|
||||
"url": "https://relay.fluxer.app",
|
||||
"description": "Production relay directory"
|
||||
}
|
||||
],
|
||||
"paths": {
|
||||
"/_health": {
|
||||
"get": {
|
||||
"operationId": "getHealth",
|
||||
"summary": "Health check",
|
||||
"description": "Returns the health status of the relay directory service.",
|
||||
"tags": ["Health"],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "Service is healthy",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/HealthCheckResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/v1/relays": {
|
||||
"get": {
|
||||
"operationId": "listRelays",
|
||||
"summary": "List available relays",
|
||||
"description": "Returns a list of available relay servers. Optionally, provide client coordinates to sort relays by proximity.",
|
||||
"tags": ["Relays"],
|
||||
"parameters": [
|
||||
{
|
||||
"name": "lat",
|
||||
"in": "query",
|
||||
"description": "Client latitude for proximity-based sorting",
|
||||
"required": false,
|
||||
"schema": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
{
|
||||
"name": "lon",
|
||||
"in": "query",
|
||||
"description": "Client longitude for proximity-based sorting",
|
||||
"required": false,
|
||||
"schema": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
{
|
||||
"name": "limit",
|
||||
"in": "query",
|
||||
"description": "Maximum number of relays to return",
|
||||
"required": false,
|
||||
"schema": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "List of available relays",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/RelayListResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/v1/relays/register": {
|
||||
"post": {
|
||||
"operationId": "registerRelay",
|
||||
"summary": "Register a new relay",
|
||||
"description": "Registers a new relay server with the directory. The relay must provide its public key for E2E encryption.",
|
||||
"tags": ["Relays"],
|
||||
"requestBody": {
|
||||
"required": true,
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/RegisterRelayRequest"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"responses": {
|
||||
"201": {
|
||||
"description": "Relay registered successfully",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/RelayInfoResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/v1/relays/{id}/status": {
|
||||
"get": {
|
||||
"operationId": "getRelayStatus",
|
||||
"summary": "Get relay status",
|
||||
"description": "Returns the current status of a specific relay server.",
|
||||
"tags": ["Relays"],
|
||||
"parameters": [
|
||||
{
|
||||
"name": "id",
|
||||
"in": "path",
|
||||
"description": "Relay UUID",
|
||||
"required": true,
|
||||
"schema": {
|
||||
"type": "string",
|
||||
"format": "uuid"
|
||||
}
|
||||
}
|
||||
],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "Relay status",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/RelayStatusResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"404": {
|
||||
"description": "Relay not found",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/RelayNotFoundError"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/v1/relays/{id}/heartbeat": {
|
||||
"post": {
|
||||
"operationId": "sendHeartbeat",
|
||||
"summary": "Send relay heartbeat",
|
||||
"description": "Sends a heartbeat to indicate the relay is still alive. Relays should send heartbeats periodically to maintain their healthy status.",
|
||||
"tags": ["Relays"],
|
||||
"parameters": [
|
||||
{
|
||||
"name": "id",
|
||||
"in": "path",
|
||||
"description": "Relay UUID",
|
||||
"required": true,
|
||||
"schema": {
|
||||
"type": "string",
|
||||
"format": "uuid"
|
||||
}
|
||||
}
|
||||
],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "Heartbeat received",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/RelayHeartbeatResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"404": {
|
||||
"description": "Relay not found",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/RelayNotFoundError"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/v1/relays/{id}": {
|
||||
"delete": {
|
||||
"operationId": "deleteRelay",
|
||||
"summary": "Unregister a relay",
|
||||
"description": "Removes a relay server from the directory.",
|
||||
"tags": ["Relays"],
|
||||
"parameters": [
|
||||
{
|
||||
"name": "id",
|
||||
"in": "path",
|
||||
"description": "Relay UUID",
|
||||
"required": true,
|
||||
"schema": {
|
||||
"type": "string",
|
||||
"format": "uuid"
|
||||
}
|
||||
}
|
||||
],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "Relay deleted",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/RelayDeletedResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"404": {
|
||||
"description": "Relay not found",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/RelayNotFoundError"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"components": {
|
||||
"schemas": {
|
||||
"HealthCheckResponse": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"status": {
|
||||
"type": "string",
|
||||
"enum": ["ok"],
|
||||
"description": "Health status"
|
||||
},
|
||||
"timestamp": {
|
||||
"type": "string",
|
||||
"format": "date-time",
|
||||
"description": "Current server timestamp"
|
||||
}
|
||||
},
|
||||
"required": ["status", "timestamp"]
|
||||
},
|
||||
"RelayInfoResponse": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"id": {
|
||||
"type": "string",
|
||||
"description": "Unique identifier for the relay"
|
||||
},
|
||||
"name": {
|
||||
"type": "string",
|
||||
"description": "Human-readable name of the relay"
|
||||
},
|
||||
"url": {
|
||||
"type": "string",
|
||||
"format": "uri",
|
||||
"description": "Base URL of the relay service"
|
||||
},
|
||||
"latitude": {
|
||||
"type": "number",
|
||||
"description": "Geographic latitude of the relay"
|
||||
},
|
||||
"longitude": {
|
||||
"type": "number",
|
||||
"description": "Geographic longitude of the relay"
|
||||
},
|
||||
"region": {
|
||||
"type": "string",
|
||||
"description": "Region identifier (e.g., eu-west, us-east)"
|
||||
},
|
||||
"capacity": {
|
||||
"type": "integer",
|
||||
"minimum": 0,
|
||||
"maximum": 9007199254740991,
|
||||
"format": "int64",
|
||||
"description": "Maximum number of connections this relay can handle"
|
||||
},
|
||||
"current_connections": {
|
||||
"type": "integer",
|
||||
"minimum": 0,
|
||||
"maximum": 9007199254740991,
|
||||
"format": "int64",
|
||||
"description": "Current number of active connections"
|
||||
},
|
||||
"public_key": {
|
||||
"type": "string",
|
||||
"description": "Base64-encoded X25519 public key for E2E encryption"
|
||||
},
|
||||
"registered_at": {
|
||||
"type": "string",
|
||||
"format": "date-time",
|
||||
"description": "ISO 8601 timestamp when the relay was registered"
|
||||
},
|
||||
"last_seen_at": {
|
||||
"type": "string",
|
||||
"format": "date-time",
|
||||
"description": "ISO 8601 timestamp of the last health check or heartbeat"
|
||||
},
|
||||
"healthy": {
|
||||
"type": "boolean",
|
||||
"description": "Whether the relay is currently healthy"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"id",
|
||||
"name",
|
||||
"url",
|
||||
"latitude",
|
||||
"longitude",
|
||||
"region",
|
||||
"capacity",
|
||||
"current_connections",
|
||||
"public_key",
|
||||
"registered_at",
|
||||
"last_seen_at",
|
||||
"healthy"
|
||||
]
|
||||
},
|
||||
"RelayWithDistanceResponse": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"id": {
|
||||
"type": "string",
|
||||
"description": "Unique identifier for the relay"
|
||||
},
|
||||
"name": {
|
||||
"type": "string",
|
||||
"description": "Human-readable name of the relay"
|
||||
},
|
||||
"url": {
|
||||
"type": "string",
|
||||
"format": "uri",
|
||||
"description": "Base URL of the relay service"
|
||||
},
|
||||
"latitude": {
|
||||
"type": "number",
|
||||
"description": "Geographic latitude of the relay"
|
||||
},
|
||||
"longitude": {
|
||||
"type": "number",
|
||||
"description": "Geographic longitude of the relay"
|
||||
},
|
||||
"region": {
|
||||
"type": "string",
|
||||
"description": "Region identifier (e.g., eu-west, us-east)"
|
||||
},
|
||||
"capacity": {
|
||||
"type": "integer",
|
||||
"minimum": 0,
|
||||
"maximum": 9007199254740991,
|
||||
"format": "int64",
|
||||
"description": "Maximum number of connections this relay can handle"
|
||||
},
|
||||
"current_connections": {
|
||||
"type": "integer",
|
||||
"minimum": 0,
|
||||
"maximum": 9007199254740991,
|
||||
"format": "int64",
|
||||
"description": "Current number of active connections"
|
||||
},
|
||||
"public_key": {
|
||||
"type": "string",
|
||||
"description": "Base64-encoded X25519 public key for E2E encryption"
|
||||
},
|
||||
"registered_at": {
|
||||
"type": "string",
|
||||
"format": "date-time",
|
||||
"description": "ISO 8601 timestamp when the relay was registered"
|
||||
},
|
||||
"last_seen_at": {
|
||||
"type": "string",
|
||||
"format": "date-time",
|
||||
"description": "ISO 8601 timestamp of the last health check or heartbeat"
|
||||
},
|
||||
"healthy": {
|
||||
"type": "boolean",
|
||||
"description": "Whether the relay is currently healthy"
|
||||
},
|
||||
"distance_km": {
|
||||
"type": "number",
|
||||
"minimum": 0,
|
||||
"description": "Distance from client location in kilometres"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"id",
|
||||
"name",
|
||||
"url",
|
||||
"latitude",
|
||||
"longitude",
|
||||
"region",
|
||||
"capacity",
|
||||
"current_connections",
|
||||
"public_key",
|
||||
"registered_at",
|
||||
"last_seen_at",
|
||||
"healthy",
|
||||
"distance_km"
|
||||
]
|
||||
},
|
||||
"RelayListResponse": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"relays": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"oneOf": [
|
||||
{
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"id": {
|
||||
"type": "string",
|
||||
"description": "Unique identifier for the relay"
|
||||
},
|
||||
"name": {
|
||||
"type": "string",
|
||||
"description": "Human-readable name of the relay"
|
||||
},
|
||||
"url": {
|
||||
"type": "string",
|
||||
"format": "uri",
|
||||
"description": "Base URL of the relay service"
|
||||
},
|
||||
"latitude": {
|
||||
"type": "number",
|
||||
"description": "Geographic latitude of the relay"
|
||||
},
|
||||
"longitude": {
|
||||
"type": "number",
|
||||
"description": "Geographic longitude of the relay"
|
||||
},
|
||||
"region": {
|
||||
"type": "string",
|
||||
"description": "Region identifier (e.g., eu-west, us-east)"
|
||||
},
|
||||
"capacity": {
|
||||
"type": "integer",
|
||||
"minimum": 0,
|
||||
"maximum": 9007199254740991,
|
||||
"format": "int64",
|
||||
"description": "Maximum number of connections this relay can handle"
|
||||
},
|
||||
"current_connections": {
|
||||
"type": "integer",
|
||||
"minimum": 0,
|
||||
"maximum": 9007199254740991,
|
||||
"format": "int64",
|
||||
"description": "Current number of active connections"
|
||||
},
|
||||
"public_key": {
|
||||
"type": "string",
|
||||
"description": "Base64-encoded X25519 public key for E2E encryption"
|
||||
},
|
||||
"registered_at": {
|
||||
"type": "string",
|
||||
"format": "date-time",
|
||||
"description": "ISO 8601 timestamp when the relay was registered"
|
||||
},
|
||||
"last_seen_at": {
|
||||
"type": "string",
|
||||
"format": "date-time",
|
||||
"description": "ISO 8601 timestamp of the last health check or heartbeat"
|
||||
},
|
||||
"healthy": {
|
||||
"type": "boolean",
|
||||
"description": "Whether the relay is currently healthy"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"id",
|
||||
"name",
|
||||
"url",
|
||||
"latitude",
|
||||
"longitude",
|
||||
"region",
|
||||
"capacity",
|
||||
"current_connections",
|
||||
"public_key",
|
||||
"registered_at",
|
||||
"last_seen_at",
|
||||
"healthy"
|
||||
]
|
||||
},
|
||||
{
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"id": {
|
||||
"type": "string",
|
||||
"description": "Unique identifier for the relay"
|
||||
},
|
||||
"name": {
|
||||
"type": "string",
|
||||
"description": "Human-readable name of the relay"
|
||||
},
|
||||
"url": {
|
||||
"type": "string",
|
||||
"format": "uri",
|
||||
"description": "Base URL of the relay service"
|
||||
},
|
||||
"latitude": {
|
||||
"type": "number",
|
||||
"description": "Geographic latitude of the relay"
|
||||
},
|
||||
"longitude": {
|
||||
"type": "number",
|
||||
"description": "Geographic longitude of the relay"
|
||||
},
|
||||
"region": {
|
||||
"type": "string",
|
||||
"description": "Region identifier (e.g., eu-west, us-east)"
|
||||
},
|
||||
"capacity": {
|
||||
"type": "integer",
|
||||
"minimum": 0,
|
||||
"maximum": 9007199254740991,
|
||||
"format": "int64",
|
||||
"description": "Maximum number of connections this relay can handle"
|
||||
},
|
||||
"current_connections": {
|
||||
"type": "integer",
|
||||
"minimum": 0,
|
||||
"maximum": 9007199254740991,
|
||||
"format": "int64",
|
||||
"description": "Current number of active connections"
|
||||
},
|
||||
"public_key": {
|
||||
"type": "string",
|
||||
"description": "Base64-encoded X25519 public key for E2E encryption"
|
||||
},
|
||||
"registered_at": {
|
||||
"type": "string",
|
||||
"format": "date-time",
|
||||
"description": "ISO 8601 timestamp when the relay was registered"
|
||||
},
|
||||
"last_seen_at": {
|
||||
"type": "string",
|
||||
"format": "date-time",
|
||||
"description": "ISO 8601 timestamp of the last health check or heartbeat"
|
||||
},
|
||||
"healthy": {
|
||||
"type": "boolean",
|
||||
"description": "Whether the relay is currently healthy"
|
||||
},
|
||||
"distance_km": {
|
||||
"type": "number",
|
||||
"minimum": 0,
|
||||
"description": "Distance from client location in kilometres"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"id",
|
||||
"name",
|
||||
"url",
|
||||
"latitude",
|
||||
"longitude",
|
||||
"region",
|
||||
"capacity",
|
||||
"current_connections",
|
||||
"public_key",
|
||||
"registered_at",
|
||||
"last_seen_at",
|
||||
"healthy",
|
||||
"distance_km"
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
"description": "List of available relays"
|
||||
},
|
||||
"count": {
|
||||
"type": "integer",
|
||||
"minimum": 0,
|
||||
"maximum": 9007199254740991,
|
||||
"format": "int64",
|
||||
"description": "Total number of relays returned"
|
||||
}
|
||||
},
|
||||
"required": ["relays", "count"]
|
||||
},
|
||||
"RelayStatusResponse": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"id": {
|
||||
"type": "string",
|
||||
"description": "Unique identifier for the relay"
|
||||
},
|
||||
"name": {
|
||||
"type": "string",
|
||||
"description": "Human-readable name of the relay"
|
||||
},
|
||||
"url": {
|
||||
"type": "string",
|
||||
"format": "uri",
|
||||
"description": "Base URL of the relay service"
|
||||
},
|
||||
"region": {
|
||||
"type": "string",
|
||||
"description": "Region identifier"
|
||||
},
|
||||
"healthy": {
|
||||
"type": "boolean",
|
||||
"description": "Whether the relay is currently healthy"
|
||||
},
|
||||
"current_connections": {
|
||||
"type": "integer",
|
||||
"minimum": 0,
|
||||
"maximum": 9007199254740991,
|
||||
"format": "int64",
|
||||
"description": "Current number of active connections"
|
||||
},
|
||||
"capacity": {
|
||||
"type": "integer",
|
||||
"minimum": 0,
|
||||
"maximum": 9007199254740991,
|
||||
"format": "int64",
|
||||
"description": "Maximum connection capacity"
|
||||
},
|
||||
"last_seen_at": {
|
||||
"type": "string",
|
||||
"format": "date-time",
|
||||
"description": "ISO 8601 timestamp of the last health check or heartbeat"
|
||||
}
|
||||
},
|
||||
"required": ["id", "name", "url", "region", "healthy", "current_connections", "capacity", "last_seen_at"]
|
||||
},
|
||||
"RelayHeartbeatResponse": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"status": {
|
||||
"type": "string",
|
||||
"enum": ["ok"],
|
||||
"description": "Confirmation that heartbeat was received"
|
||||
}
|
||||
},
|
||||
"required": ["status"]
|
||||
},
|
||||
"RelayDeletedResponse": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"status": {
|
||||
"type": "string",
|
||||
"enum": ["deleted"],
|
||||
"description": "Confirmation that relay was deleted"
|
||||
}
|
||||
},
|
||||
"required": ["status"]
|
||||
},
|
||||
"RegisterRelayRequest": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"name": {
|
||||
"type": "string",
|
||||
"minLength": 1,
|
||||
"maxLength": 100,
|
||||
"description": "Human-readable name of the relay"
|
||||
},
|
||||
"url": {
|
||||
"type": "string",
|
||||
"format": "uri",
|
||||
"description": "Base URL of the relay service"
|
||||
},
|
||||
"latitude": {
|
||||
"type": "number",
|
||||
"minimum": -90,
|
||||
"maximum": 90,
|
||||
"description": "Geographic latitude of the relay"
|
||||
},
|
||||
"longitude": {
|
||||
"type": "number",
|
||||
"minimum": -180,
|
||||
"maximum": 180,
|
||||
"description": "Geographic longitude of the relay"
|
||||
},
|
||||
"region": {
|
||||
"type": "string",
|
||||
"minLength": 1,
|
||||
"maxLength": 50,
|
||||
"description": "Region identifier"
|
||||
},
|
||||
"capacity": {
|
||||
"type": "integer",
|
||||
"minimum": 1,
|
||||
"maximum": 9007199254740991,
|
||||
"format": "int64",
|
||||
"description": "Maximum connection capacity"
|
||||
},
|
||||
"public_key": {
|
||||
"type": "string",
|
||||
"minLength": 1,
|
||||
"description": "Base64-encoded X25519 public key for E2E encryption"
|
||||
}
|
||||
},
|
||||
"required": ["name", "url", "latitude", "longitude", "public_key"]
|
||||
},
|
||||
"RelayIdParam": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"id": {
|
||||
"type": "string",
|
||||
"format": "uuid",
|
||||
"description": "Relay UUID"
|
||||
}
|
||||
},
|
||||
"required": ["id"]
|
||||
},
|
||||
"RelayListQuery": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"lat": {
|
||||
"type": "string",
|
||||
"description": "Client latitude for proximity sorting"
|
||||
},
|
||||
"lon": {
|
||||
"type": "string",
|
||||
"description": "Client longitude for proximity sorting"
|
||||
},
|
||||
"limit": {
|
||||
"type": "string",
|
||||
"description": "Maximum number of relays to return"
|
||||
}
|
||||
}
|
||||
},
|
||||
"RelayNotFoundError": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"error": {
|
||||
"type": "string",
|
||||
"description": "Error message"
|
||||
},
|
||||
"code": {
|
||||
"type": "string",
|
||||
"enum": ["RELAY_NOT_FOUND"],
|
||||
"description": "Error code"
|
||||
}
|
||||
},
|
||||
"required": ["error", "code"]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user