The BAPS3 internal API is mainly intended for use when joining servers together to form services. While it is possible to connect clients to services using the internal API, we also specify a resource-based external API intended for consumption specifically by clients.
The external API uses HTTPS as an underlying protocol, and is based on the concept of projecting the visible state of a service as a resource hierarchy, with HTTP verbs representing the possible interactions with said resources. This approach is inspired by the Representational State Transfer school of API design.
BAPS3 features may define a number of resources that participate in the external API. Resources are represented in the external API as elements in the URL hierarchy.
For example, a playlist service might define, through its constituent
features, a 'playlist' resource representing the current list of
enqueued items. Then, each playlist item would be available via its
position (the first item would then be playlist/0), or its unique
hash (perhaps playlist/h39acf3a31d482).
HTTPS requests on these resources could either represent a query on the internal state of the service, or an equivalent Internal API request (for example, a DELETE on 'playlist/0' might represent a 'dequeue 0' internal API command).
We define a separate external API because:
HTTPS is a ubiquitous protocol and is implemented in more areas than the bespoke internal API protocol;
Web clients can make easier use of a HTTPS-based protocol than a raw TCP-based protocol;
Allows for simple authentication of requests, using the existing HTTP authentication framework;
The resource-hierarchy view of BAPS3 is easier to inspect and query (for both debug and production purposes) than a command-based view.