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 enters 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 apps flow:

• An Application queries the User-Agent for available services. It provides requirements in its query which describe the needed resources.
• The User-Agent prompts the User to choose from known services, or to enter the domain of a service which provides the needed resources.
• The User-Agent returns a URL 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,
  "title": "My Example Service",
  "description": "Demonstrates the PSA service document",
  "links": [{
    "rel": "http://api-spec.com/address-book",
    "title": "Example.com's User Listing API",
    "href": "https://example.com/v1/users"
  }, {
    "rel": "http://api-spec.com/clock",
    "title": "Get-current-time API",
    "href": "https://example.com/v1/get-time"
  }]
}

The fields in depth:

• PSA: required Number. Declares the use of the PSA spec and provides the version used. Should be set to 1.
• title: optional String. The title of the service. (Optional but recommended.)
• description: optional String. The description of the service. (Optional but recommended.)
• links: required Array. A list of links to resources provided by the service.
• links.*: Object.
• links.*.rel: required String. A space-separated list of URLs which describe the resource provided.
• links.*.title: optional String. The title of the resource. (Optional but recommended.)
• links.*.href: required String. The URL of the resource. Must be on the same domain as the PSA document, or on a subdomain of the PSA document.

PSA Document Hosting

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

Alternatives

One alternative is to read Link headers after a GET/HEAD request to the service root path. However, this adds overhead to every root request, and in some cases can be harder to configure than a single document at a .well-known directory.

Another alternative is to GET the root path with an Accept header specifying a json content. The returned document could then be the PSA document. However, again, content-type negotiation can be difficult to configure in some cases, and the service may already have a JSON response at the root which would make adopting this standard difficult.