BAPS3 Specification

Core

Certain requests and responses should be implemented by all BAPS3 servers understanding the Internal API, and are not associated with any FEATURES flag. These are enumerated here.

Requests

dump — dump snapshot of state

Synopsis

dump

Description

dump asks the service to relay as much of its current, variable state as possible. This should consist of the initial responses, less OHAI and FEATURES if they cannot change over the service’s lifetime. It may omit other non-changing parts of the initial responses.

quit — quit server stack

Synopsis

quit

Description

quit is a request to a server, and all servers downstream from it, to close gracefully.

The server(s) do not need to acknowledge the quit in any manner other than disconnecting upstream connections.

Responses

FAIL — server failure

Synopsis

FAIL <MESSAGE>

Description

FAIL must be sent to acknowledge a request that has failed. Said request must be provided, in a form identical to the original request (up to encoding and escaping differences), as the third and later words of the FAIL response.

The second word of the FAIL response is a human-readable error message. Future revisions of the spec may define a structure for this error message.

OK — command received

Synopsis

OK <COMMAND> [ARGS…​]

Description

OK must be sent to acknowledge a request that has successfully terminated. Said request must be provided, in a form identical to the original request (up to encoding and escaping differences), as the second and later words of the OK response.

OHAI — server welcome

Synopsis

OHAI <IDENTIFIER>

Description

OHAI must be sent as the first initial response given to any connecting upstream, and identifies the server (as well as the BAPS3 internal protocol).

Any client connecting to a BAPS3 Internal API-compliant server may take the absence of an initial OHAI as grounds for rejecting the server. This is not an absolute requirement.

A server that is the upstream of a second server should reference that server’s full identifier as part of its OHAI response. For example, a listmaster server connecting to a playslave` server should report itself as `listmaster/playslave.

A client may use the server’s identifier as a hint for enabling server-specific behaviour: this should be restricted to working around quirks and bugs in poorly constructed servers, and should not be used for enabling specific functionality (the FEATURES system should be preferred instead).

STATE — state update

Synopsis

STATE <STATE-NAME>

Description

STATE should be sent when:

  • A new upstream connects to a server, as the final initial response; or

  • The server’s state changes.

The list of available states always contains the following:

  • Quitting: the server is preparing to quit, and clients should not send responses;

  • Ready: the server can take responses, but there is no other state that better defines the server’s current status.

The list of available states is added to by certain features. For example, the PlayStop feature adds the Playing and Stopped states, and mandates that the initial state is Stopped unless any other feature specifically overrides that mandate. Servers should not use Ready if another feature state better fits its present situation.

WHAT — bad command

Synopsis

WHAT <MESSAGE> <COMMAND> [ARGS…​]

Description

WHAT must be sent to acknowledge an invalid request: one that does not fit the syntax of its declared command, or one with an unknown command. Said request must be provided, in a form identical to the original request (up to encoding and escaping differences), as the third and later words of the WHAT response.

The second word of the WHAT response is a human-readable error message. Future revisions of the spec may define a structure for this error message.

Resources

/

The root resource. Every resource is a descendant of this resource.

Behaves as a simple composite resource for all actions.

/control

The control resource, which contains both read-only information about the service, and writable flags that affect the service’s running and configuration.

Behaves as a simple composite resource for all actions.

/control/features

Contains a list of strings representing the implemented features on the queried service (those returned by a FEATURES Internal API response from this service).

All actions apart from GET are forbidden.

GET

GET responses must return a list of strings that correspond exactly to the names of the features implemented by the queried service. There is no defined ordering on the strings.

Example

If a service provides FEATURES PlayStop FileLoad End, the GET response value for /control/features may be ["PlayStop", "FileLoad", "End"] (or any permutation thereof).

/control/serverid

Contains the server identifier that would be returned by the OHAI Internal API response.

All actions apart from GET are forbidden.

Example

If a service identifies as OHAI listd-0.3.0/playd-0.3.0, then the GET response value for /control/serverid shall be "listd-0.3.0/playd-0.3.0".

/control/state

The current state of this service.

GET

GET requests should return a Boolean: false if the service is known to be shutting down, and true otherwise. Generally, this will be the latter, as non-running services will likely close their External API endpoints upon starting to exit.

PUT

Attempts to set the state to the given state. The state payload must be a string, and should be interpreted in a case-insensitive manner.

Any unknown states, or malformed payloads, should result in a malformed value error.

access The semantics of each state is specified alongside the documentation for the feature introducing that state. The semantics of the two core states are as follows:

Ready

Services should reject an attempt to set the state to Ready.

Quitting

Services should interpret this as equivalent to a QUIT Internal API request.

DELETE

Behaves as a PUT with the payload value Quitting.