New Compact API Format

[pablohoch]

Adds a new JSON format for the Web API. The current format remains supported. Also adds internal APIs to the OpenAPI spec.

Currently, the response format is automatically determined based on the request format.

Breaking change: For GET requests or when the request message cannot be parsed, the new compact format is now returned.

The new format should enable better OpenAPI and JSON Schema support and more compact API requests and responses.

TODO:

• Add an option to chose the desired response format. Needed for GET requests, parse errors etc. (Maybe an URL parameter like ?format=X?) -> Probably not needed
• Chose a default format (when none is specified in the request/can't be determined from the request)
• Add support for the formats to the WebSocket API
• Update protocol tool to support the new format:
  • OpenAPI generator
  • JSON Schema generator
  • TypeScript generator (optional) -> maybe later
• Make sure that the OpenAPI spec matches the default format
• Check if changes are needed to allow additional fields in the OpenAPI spec (forward compatibility)
  • In the OpenAPI specs, "additionalProperties": true is now set explicitly. Although this is the default value, some tools such as the OpenAPI Generator incorrectly use false as default (see their disallowAdditionalPropertiesIfNotPresent option). With this change, the generated code should now accept additional properties by default.

Supported Formats

The following formats are supported:

Default FlatBuffers (Current API)

POST /anywhere (HTTP target is ignored)

Request:

{
	"destination": {
		"target": "/paxmon/status"
	},
	"content_type": "PaxMonStatusRequest",
	"content": {
		"universe": 0
	}
}

Response:

{
	"destination": {
		"type": "Module",
		"target": ""
	},
	"content_type": "PaxMonStatusResponse",
	"content": {
		"system_time": 1682003768,
		"multiverse_id": 1682003768813,
		"active_groups": 1234,
		"trip_count": 5678
	},
	"id": 1
}

Type Tags in Unions (New)

POST /anywhere (HTTP target is ignored)

Request:

{
	"destination": {
		"target": "/paxmon/status"
	},
	"content": {
		"_type": "PaxMonStatusRequest",
		"universe": 0
	}
}

Response:

{
	"destination": {
		"type": "Module",
		"target": ""
	},
	"content": {
		"_type": "PaxMonStatusResponse",
		"system_time": 1682003768,
		"multiverse_id": 1682003768813,
		"active_groups": 1234,
		"trip_count": 5678
	},
	"id": 1
}

The _type fields are only included in union fields.

Type Tags in Unions + Content Only (New Default Format)

POST /paxmon/status (HTTP target specifies the message target/API endpoint)

Request:

{
	"_type": "PaxMonStatusRequest",
	"universe": 0
}

Response:

{
	"_type": "PaxMonStatusResponse",
	"system_time": 1682003768,
	"multiverse_id": 1682003768813,
	"active_groups": 1234,
	"trip_count": 5678
}

OpenAPI

Since types can be used in unions (in which case they have a _type field) and outside of unions (in which case they don't have a _ type field), two different schemas are required for types that are used in both scenarios. If a type is used in a union, a T is appended to the name (e.g. Station -> StationT). Only the required types are generated (e.g. for the top-level message types, only types with the T suffix are generated).