PSA Web Service Discovery Protocol

PSA is a protocol for discovering Web service APIs. It empowers users to configure applications by dynamically selecting their endpoints.

Discovery flow:

• The User arrives at a site over HTTP.
• The User-Agent automatically downloads the PSA document and presents its contents to the user.
• The User chooses services from the PSA document, which the User-Agent saves to an internal database.

Configuration flow:

• An Application queries the internal database for available services.
• (Optionally) The User-Agent asks the User to choose from the available services.
• The User-Agent returns an endpoint for the Application to consume.

Motivation

Primary: Beaker and Hashbase are built to work together. Hashbase provides cloud hosting for Beaker archives. We want to enable interactions with Hashbase through Beaker's builtin interfaces. However, we do not want to hardwire Hashbase to the Beaker browser. PSA enables Beaker to discover and integrate with any service that adheres to Hashbase's protocols.

Secondary: Beaker can act as a matchmaker between Web services and installed applications. As the user browses, Beaker can present them with options to consume services discovered by PSA, perhaps by using compatible installed applications.

PSA Document

A PSA Document is a JSON document. It includes objects which specify the service APIs available.

Example:

{
  "PSA": 1,
  "name": "My Example Service",
  "description": "Demonstrates the PSA service document",
  "url": "https://example.com/",
  "apis": [{
    "type": "http://api-spec.com/address-book",
    "description": "Example.com's User Listing API",
    "url": "https://example.com/v1/users"
  }, {
    "type": "http://api-spec.com/clock",
    "description": "Get-current-time API",
    "url": "https://example.com/v1/get-time"
  }]
}

The fields in depth:

TODO

PSA Document Hosting

Servers should host the PSA document at /.well-known/psa.