| JVM | Platform | Status |
|---|---|---|
| OpenJDK (Temurin) Current | Linux |  |
| OpenJDK (Temurin) LTS | Linux |  |
| OpenJDK (Temurin) Current | Windows |  |
| OpenJDK (Temurin) LTS | Windows |  |
The ventrad package provides a JSON protocol for advertising HTTP endpoint
protocol versions.
ventrad is a trivial protocol for announcing a set of protocols
exposed by a set of HTTP endpoints.
A client connecting to a root endpoint reads a JSON document delivered with
the content type application/ventrad+json. The document details which
protocols are supported by the given server, and instructs the client on
where to go in order to use those protocols.
As an example:
$ curl https://api.example.com/
{
"%Schema" : "urn:com.io7m.ventrad:1",
"Protocols" : [ {
"Id" : "urn:com.io7m.cardant:inventory",
"VersionMajor" : 1,
"VersionMinor" : 0,
"Endpoint" : "/inventory/1/0/",
"Description" : "Cardant Inventory service v1.0"
}, {
"Id" : "urn:com.io7m.cardant:inventory",
"VersionMajor" : 1,
"VersionMinor" : 1,
"Endpoint" : "/inventory/1/1/",
"Description" : "Cardant Inventory service v1.1"
}, {
"Id" : "urn:com.io7m.cardant:inventory",
"VersionMajor" : 2,
"VersionMinor" : 0,
"Endpoint" : "/inventory/2/0/",
"Description" : "Cardant Inventory service v2.0"
} ]
}
The JSON document MUST include a %Schema property with a value of
urn:com.io7m.ventrad:1.
The Protocols property is a non-null array of Protocol objects. A
Protocol object contains a unique identifier for the protocol, a non-negative
major and minor protocol version, a URI indicating the endpoint that uses
the protocol, and a humanly-readable description of the protocol and the
version. All fields are required and must be non-null.
The served document MUST conform to the given schema:
{
"$schema" : "https://json-schema.org/draft/2020-12/schema",
"$defs" : {
"VProtocol" : {
"type" : "object",
"properties" : {
"Description" : {
"type" : "string",
"description" : "A humanly-readable description of the protocol."
},
"Endpoint" : {
"type" : "string",
"format" : "uri",
"description" : "The endpoint to be used by clients for this protocol."
},
"Id" : {
"type" : "string",
"description" : "The protocol identifier."
},
"VersionMajor" : {
"type" : "integer",
"description" : "The protocol major version."
},
"VersionMinor" : {
"type" : "integer",
"description" : "The protocol minor version."
}
},
"required" : [ "Description", "Endpoint", "Id", "VersionMajor", "VersionMinor" ],
"description" : "A single version of a single protocol."
}
},
"type" : "object",
"properties" : {
"%Schema" : {
"type" : "string"
},
"Protocols" : {
"description" : "The protocols.",
"type" : "array",
"items" : {
"$ref" : "#/$defs/VProtocol"
}
}
},
"required" : [ "%Schema", "Protocols" ],
"description" : "A set of supported protocols in priority order."
}