V1.1.0: Data Structure Version Naming

[perlboy]

Request For Clarification

Following release to the Slate site of V1.1.0 yesterday we have now initiated analysis of changes using the diff previously provided in #56.

With reference to slate/source/includes/swagger/cds_full.json the structure name specified is BankingProductV2 and BankingProductDetailV2.

Is this the intended approach for communicating new versions of payloads? If so, will all existing payloads be renamed appropriately to be suffixed with V1? How does the DSB intend to communicate mixed mode versioning within the Swagger specification?

[perlboy]

Further on this, we note that CommonDiscoveryStatus_data has been renamed to ResponseCommonDiscoveryStatus_data. This change is not noted in the supplied changelog.

[CDR-API-Stream]

The swagger provided in the standards are designed to be representative of the standards but are not normative. The standards site itself is the normative definition of the standards.

Changes to model names within the swagger files are not considered material changes to the standards.

[perlboy]

The swagger provided in the standards are designed to be representative of the standards but are not normative. The standards site itself is the normative definition of the standards.
Changes to model names within the swagger files are not considered material changes to the standards.

These statements appear to be a direct violation of:

Principle 4: APIs provide a good developer experience
To ensure that the entry hurdle for new developers is low the experience of the developers that are building clients using the APIs will be considered. The ability for a developer to easily understand and write code using the APIs in modern development environments should be facilitated by the API standards.

By the statements provided a developer can no longer reliably use the swagger definition and must trawl a html site now spanning 236 A4 pages. In addition, "modern development environments" are heavily reliant upon the OpenAPI specifications.

If the intention of the DSB is to provide Swaggers which are not aligned with the published documentation their presence is more detrimental than useful.

[CDR-API-Stream]

The swagger provided in the standards are designed to be representative of the standards but are not normative. The standards site itself is the normative definition of the standards.
Changes to model names within the swagger files are not considered material changes to the standards.

These statements appear to be a direct violation of:

Principle 4: APIs provide a good developer experience
To ensure that the entry hurdle for new developers is low the experience of the developers that are building clients using the APIs will be considered. The ability for a developer to easily understand and write code using the APIs in modern development environments should be facilitated by the API standards.

The contravention of this principle is not self-evident. The APIs defined by the standards are the same and are still intended to provide a good experience.

By the statements provided a developer can no longer reliably use the swagger definition and must trawl a html site now spanning 236 A4 pages. In addition, "modern development environments" are heavily reliant upon the OpenAPI specifications.

There is no need to trawl the html site. The release notes specify the material changes to the standards when each new version is released.

If the intention of the DSB is to provide Swaggers which are not aligned with the published documentation their presence is more detrimental than useful.

The swagger is aligned to the published documentation. In fact, the published documentation is largely generated from the swagger. The previous comments only indicate that model names are not material to the standard so when they change the release notes do not capture the change. As long as the model names are unique and the references are accurate they serve their purpose.

[perlboy]

As noted in #60 there appears to be a selective interpretation about what is included in the changelog. With this knowledge it is inevitable that an implementer must analyse the 236 pages of specification to gain confidence that changes have been suitably identified.

How these "non material" changes are communicated is entirely up to the DSB but deliberately omitting this communication is neither helpful to an implementer nor conducive to a consistent understanding across implementing parties.

[CDR-API-Stream]

Can we close this query? If continued discussion on the topic is needed it would be easier for others to follow if it was on a single thread on #60?

[perlboy]

The DSB appears to be willing to alter it's swagger definition when it suits it's own customised and highly irregular documentation generation process but ignore simple requests for the changes to be noted. Evidently what provides a "good developer experience" is governed by what makes it easier for @CDR-API-Stream to release documentation. There is no value in attempting to articulate this further.