5 Server Capabilities

As described in section 2.1.1, the session-initiation process provides for a negotiation of the protocols and object types that will be exchanged in a session. ETP also provide a mechanism for clients to “pre-discover” the capabilities of a server out-of-band of the WebSocket connection, using a simple HTTP GET of a JSON object. This mechanism is not strictly required for every ETP server, but certain implementations of ETP for specific workloads and XML standards may require it to be implemented (for example, it may be required for a WITSML store). Use of these mechanisms will be documented in the companion implementation specifications for each Energistics ML.

• The URL for the capabilities document can be found by appending the string ‘well-known/etp-server-capabilities’ to the HTTP-equivalent URL of the ETP WebSocket end point. For example, if you have an ETP server listening at wss://etp.sample.org:8080, then the server capabilities document could be retrieved with an HTTP GET from https://etp.sample.org:8080/.well-known/etp-server-capabilities.
• The capabilities document MUST match ‘TLS-ness’ of the WebSocket connection. That is, if the WebSocket address is at ws://, then the document MUST be at http://. If the WebSocket is at wss://, then the document MUST be at https://.
• The returned resource MUST have a content type of application/json.
• The contents of the returned JSON object MUST match an Avro JSON serialization of the Energistics.Datatypes.ServerCapabilities structure defined in Section 3.3.2 Record: ServerCapabilities .
• Additional fields may be present in the JSON document, but they are not part of the standard.
• The capabilities document MAY be a protected resource, but it is not required to be so.