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.

Potential 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.

Potential configuration flow:

• The User arrives at a config interface.
• The config interface asks the user for a service.
• The user entires the service's domain.
• The interface fetches the PSA document and finds all usable services.
• The interface presents the discovered information the User for confirmation.

Potential API for app consumption:

• 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.

Primary: In the case of configuration, Users should not be expected to copy and paste specific URLs. They should instead be able to give the service's domain to the config application. Because services frequently vary in the paths they use for their APIs, some kind of lookup is required.

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.