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

>
> In a typical enterprise system, if internal component A (e.g. a database
> server) and internal component B (e.g. a logging service) want to talk to
> each other, what's wrong with doing that with an HTTP REST API?
>
Absolutely nothing, if you're building a proprietary system.

However, If we're intending to standardize for interoperability, AND if the
internal workflow we intend to manage through these APIs intersects with an
external behavior that's intended to support self-sovereignty, then we have
to model the problem space more thoughtfully. We don't have to throw out
HTTP REST; we just have acknowledge in our internal standard that we're
actually wrestling a more complex problem than we perceived at first
glance. It's a problem that might involve the other party initiating--so we
need to standardize information flows the other direction (not just from
controller to web service that initiates external conversations, but also
from external conversations through web service back to controller who
listens on a web hook or similar).

> Those internal components don't need DID-to-DID connections between each
> other, they don't need DID Auth, JOSE, forwarding messages, etc.
>
Agreed. But if they don't use that stuff, they need the moral equivalent of
them. When an external party initiates, how does the web service that fires
the web hook to some internal software translate from the world of DIDs
that will be used externally to the world of certs and sessions that we
want to use internally? (Translation is usually only contemplated one
direction--how to authenticate the controller to the web service it
invokes--not how to authenticate the web service to the web hook it
triggers in the opposite direction.) If you don't standardize this, then
you end up without drop-in interop, because every system will handle
authentication differently.

Your internal HTTP REST calls are presumably going to be dealing with JSON
payloads, right? Considering there will be a standard, external way to
express things like what credential you want to receive, as JSON, how wise
is it to invent an entirely different JSON payload to express the same idea
for your REST calls?

I am not taking a strong position that everything must be identical and
aligned between external and internal. I am asserting something weaker:
that an internal API for controlling external X should start with external
X as its foundational assumption, and reason at least in part from X to
derive its internal requirements. Reasoning only about requirements
surfaced from an internal perspective will end up weakening X. From your
later comments, Markus, I think we are actually in agreement on this weaker
position. Having articulated this principle and seen heads nod, I'm feeling
very cheerful. Thanks for the smart dialog about it.

> If a company today wants to integrate the Evernym issuing product into
> their infrastructure, what do they have to do? Is there a DIDComm
> connection between their internal component and the Evernym component, or
> is there some other interface? And how hard would it be for them to switch,
> if they later decide that they want to use another issuing product instead
> of the Evernym one? This is basically what the proposed Work Item is meant
> to address.
>
The company has to write what we call a "controller." This controller makes
RESTful web service calls to EV's external protocol functionality to drive
it--so in that sense it is very much in line with your vision, and with
work that I know others are doing in the community. However, the controller
must also expose web hooks so it can be called in the other direction
(e.g., to decide whether it actually wants to proceed with an issuance
proposed by an external party, and to provide data from backend database,
to insert into a credential). And these web hooks require the invoker to
authenticate without using a client-side cert. Note that the second half of
its contract is just as important as the first half, that it cannot be
specified in Swagger, and that it has a gravitational pull on the mental
model for the first half of the contract.

FWIW, one other conceptual difference between EV's current vision and what
you have proposed thus far is that EV's current URL namespace contemplates
"credential" as a noun being two-sided: there are credentials to be issued
(or that have been issued in the past)--and there are credentials held and
used to prove. /credential/issued/{credid} and /credential/held/{credid},
instead of just /credential/{credid}. Today all of us make the simplifying
assumption that an API for issuers and an API for holders are different
APIs. However, tomorrow I expect it to be the case that, right in the
middle of issuance, a prospective holder might challenge the issuer to
prove they are accredited. This makes the purity of the issuer role (and
thus of the URL namespace) suspect.