the intersection between Swagger-style APIs and SSI/decentralized identity

Markus has recently proposed a work item for the CCG to develop
Swagger-style APIs for issuers and verifiers. Justin has recently proposed
a charter for a TxAuth group to start working on HTTP-based APIs to
accomplish delegation. Digital Bazaar has advocated their RESTful
Credential Handler API (CHAPI) in CCG and other circles as well. No doubt
many others on this thread are aware of efforts to standardize APIs with
similar style and similar intersection to the SSI/decentralized identity
space.

I would like to raise a red flag about such efforts, and trigger a
thoughtful follow-up conversation. I love Swagger-style APIs and have
advocated them extensively at past junctures of my career, but I am
concerned that they are exactly the wrong thing to standardize right now.
I'll explain my concerns below, in red, and then offer an alternative path
that has most of the same benefits, in blue.

1. RESTful APIs are web-only.

How do two farmers with cheap android devices in the highlands of Bolivia
(or a Canadian Mounty and a speeder on a lonely highway in Yukon Territory,
or friends in Frankfurt whose cell service has a brownlout, or two
anti-government protesters) use RESTful APIs to transact business? If the
answer is, "they subscribe to a service in the cloud so they can talk
device-to-device," I hope we are embarrassed. We need something that also
works over BlueTooth and email and other transports where a web server
isn't a component.

By standardizing a solution that doesn't think about these scenarios, we
are further marginalizing them, and we are enthroning a
*you-must-be-connected-and-you-can-be-surveilled* model that guarantees
*it-isnt-a-standard* FUD for any other efforts to fix the problem.

2. RESTful APIs perpetuate the PKI model that we claim to be replacing with
DIDs.

Servers are authenticated in these APIs with a cert. Clients are
authenticated with a session that follows from an OAuth token or an API key
or basic auth material. It is possible to imagine "DID Auth" being used for
a client of a RESTful API, and there have been several efforts to describe
and standardize such a thing. So far, none has meaningful traction, so all
APIs in the SSI space that use APIs are also allowing non-DID
authentication for clients. But even if we solve the problem for the client
side, nobody is proposing to solve the problem for the server side.
Institutions in these APIs don't use DIDs for anything meaningful. Thus
none of the decentralized properties of DIDs are brought to bear for the
server side of the interaction, and any decentralized qualities of DIDs are
relegated to minor, optional status for clients.

3. RESTful APIs foster a power imbalance

What if there's a standard way for institutions to be a verifier or issuer,
but no way for ordinary people to be a verifier or issuer? Or a standard
way for institutions to delegate, but no way for ordinary people to do it?
That's effectively what APIs like the ones I mentioned above guarantee.
There are multiple reasons why, including:

   - Institutions have web servers; farmers in Bolivia don't. (Saying that
   they *could* is not helpful; we're just creating more adoption burden for
   SSI by making the tech harder and more expensive for them.)
   - Servers can't make the first move in RESTful APIs; everything begins
   when a client initiates the interaction. This makes it natural for an
   institution (or a regulatory regime) to impose terms of service or
   reputation criteria on a client, and unnatural for a client to do the
   opposite. It's also convenient for hackers and surveillers, since they know
   they can catch all interactions at inception by simply listening on the
   server.
   - Because these APIs are online-only, and because the server always
   waits for the client to make the first move, they can only be operated by
   those who have a 24x7x365 cloud presence. Institutions and ordinary people
   don't have equal access to 24x7x365 cloud capabilities.
   - Because these APIs are secured on the server side by a cert, they can
   only be operated by those who have access to expensive, premium,
   centralized reputation. Again, institutions and people don't have equal
   access to this.

This is not an exhaustive list of my concerns, but I think it's enough to
trigger a conversation.

Proposed Alternative

We create web APIs, but we think about them differently. We conceive of all
of them as exchanges of messages that could also be accomplished over
BlueTooth, email, etc. HTTP(S) is just another transport, where messages
happen to be passed by HTTP POST (or GET, as appropriate). Security
properties associated with the exchange are based on the control of DIDs
and embodied in the messages themselves (e.g., through encryption/signing),
not in a transport layer. All semantics for the interaction are conveyed by
the message content. The traditional URL namespacing of Swagger can still
exist, but it becomes less interesting, since the message content must be
enough to convey semantics on its own (so the messages are enough in other
transports). Either party can initiate an interaction. Institutions and
people are actually peers.

This is the world of didcomm and application-level protocols built atop it;
it's described in Aries RFC 0003
<https://github.com/hyperledger/aries-rfcs/blob/master/concepts/0003-protocols/README.md>.
But before folks get their hackles up about not wanting to work with Aries
or DIF, note that I didn't propose that Aries protocols have to be the
basis for this approach. Instead, I proposed some characteristics we need
to avoid. Can we explore that assertion on its merits, without getting
immediately entangled in politics?

There are already maybe 8-10 software stacks, some independent from top to
bottom, that implement an "API" for issuing credentials and an "API" for
verifying presentations based on the model I just articulated. These
implementations are demonstrably interoperable with one another. By
proposing a new work item for a Swagger API for issuance and verification,
we are walking away from interoperability with these implementations, and
we are incurring all of the architectural disadvantages I highlighted in
red above.

What if we did this instead?

   - Agree that for issuance and verification, the goal about payloads and
   sequencing for HTTP calls should be alignment between those defined in the
   Aries protocol and those used by people who aren't Aries-centric. This
   could involve give and take in either direction; I'm not proposing that it
   has to be done by simply adopting the Aries work.
   - Agree not to depend on HTTP-specific constructs (e.g., HTTP headers,
   HTTP status codes) to signal important semantics--so the payloads could be
   exchanged over BlueTooth or email just as easily.
   - Agree that, while URL namespacing gives us a nice hook into
   Swagger-oriented tools, all semantics required for the interaction are
   detectable from the payloads themselves.

Then we'd have an HTTP solution that is Swagger-compatible but not limited
to HTTP. The "API" we created would be interoperable on a much broader
canvas than simple web.

If we further agreed to this:

   - Authentication of both parties in the interaction will be done on the
   basis of DID control, not on the basis of certs.

Then we'd also eliminate the dependence on the web's flawed PKI model, and
the power imbalance of today's web. But I know this is more controversial.