principles/coverage.rst: mandating full coverage?

[monkeypants]

The functional coverage requirement is currently set to "MUST". I understand that full coverage is much more valuable than almost-full coverage (because it make competition between implementations possible), but does a MUST requirement create a perverse incentive to avoid publishing a useful (but functionally incomplete) API?

The larger and more sophisticated the "full transaction" is, the more likely that there exists some partial-coverage APIs that are genuinely useful in their own right.

What if an there was an opportunity to implement a potentially useful functional subcomponent, but no opportunity existed to commit to a full coverage component in the near term? Would we want someone to chose not publish a potentially useful API to avoid a non-compliance finding?

The purpose of this ticket is to seek peoples views on this issue. Please comment or at least vote (+1 = mandate coverage, -1 = encourage full coverage but don't mandate it)

[monkeypants]

What if someone didn't want to publish an API for some reason, would a MUST requirement create an incentive for them to make their transaction more complex / coarser grained than it otherwise would be, just to bolster the effectiveness of the compliance-cost counterargument?

[chris-beer]

(I assume people can comment here and don't have to go through the git issues endpoint?)

What about (in terms of criteria as currently written): "Any function that is available via a retail UI which is API driven, must also expose the same API for wholesale use."

As it stands, the risk as you point out is that on the surface is that agencies can get caught in a "I must do this, so anything is better than nothing".

Consider the case of an agency which is commited to DT but has a heavy (legacy) investment in a retail UI solultion/presence which has no exposable (or indeed any) API. While committed to DT, they may have already flagged that the EOL for the retail UI is still 2-3 years away. Full coverage becomes an issue as they can't simply expose existing API functionality - rather they will need to buy/build the capability in on a fast track in order to meet the requirement.

Beyond simple conformance - the requirement as written seems to suggest that what is being aimed at is more related to HATEOS principles in that we want to avoid developers needing to go out of band to complete a transaction. So is the conformance criteria more about ensuring that developers have the documentation (beyond the API proper) about the transaction and it's lifecycle, including a road map for when non-API'd functions will likely be made into an API for use? (i.e. transparency on business reasons not to do something, or when things will be done (and developer feedback sought) will assist in mitigating a sub-optimal developer/user experience.)

Just 2 cents...

[monkeypants]

we want to avoid developers needing to go out of band to complete a transaction

yes, exactly. That's the purpose of "coverage".

So is the conformance criteria more about ensuring that developers have the documentation (beyond the API proper) about the transaction and it's lifecycle, including a road map for when non-API'd functions will likely be made into an API for use? (i.e. transparency on business reasons not to do something, or when things will be done (and developer feedback sought) will assist in mitigating a sub-optimal developer/user experience.)

Yes. I think maybe we should make "coverage" a SHOULD conformance criteria, with the details that "If not full coverage, then SHOULD provide roadmap documentation etc".

Do you think that covers it?

[chris-beer]

While personally I think it would be enough (developer experience and feedback wouldl likely push agencies to turn the SHOULD into an internal MUST over time if only from a dog fooding perspective let alone no one wanting to be the "poor" DX agency to deal with) - I suspect a more realistic yet presciptive approach might be:

1) Any function that is available via a retail UI SHOULD also be available as a wholesale API.

2) Additionally, agencies MUST provide roadmap documentation (etc) regardless of conformance with (1).

(Plain english: Either API all the things, or plan to API all the things. Either way - you have to tell developers what you have done, or what you are planning to do (so you can get feedback etc as well as having awesome DX)).