Complete release of an API - checklist

[jordonezlucena]

Develop a checklist for an "API is ready to use". Which deliverables are necessary for a complete release of an API?

[shilpa-padgaonkar]

@jordonezlucena : Hi Jose, Does this overlap with API-Readiness-Checklist or is the expectation completely different here in terms of requirements?

[jordonezlucena]

After offline discussion, the proposal is to use API-Readiness-Checklist as a basis, but some clarifications shall be made:

• Within the API lifecycle, clarify that the API-Readiness-Checklist captures the conditions that allows marking an API as CAMARA validated, stable, and therefore available for deployment/rollout in production environments.
• The description of security review (no.7) shall be clearer, without any vague interpretation. For example, make use of Auth2.0 protocol for AuthN/Z together with OpenID connect. See discussions on issue #62.
• CAMARA deliverable for an API:
  • Clarify that API spec (no.2), API documentation (no.3) and API test cases (API Test Plan, no.5) will be packaged into this deliverable.
  • Clarify whether user stories (no.4) will be included in this deliverable, or kept internal.
• We don't yet have template for API Test Template. This is to be worked out on issue #61

Another topic that came into discussion in this issue #59 is API versioning. The following conclusions are drawn:

• API versioning will be using 3-digit format (version x.y.z).
• The usage of the 3-digit will be captured in the new version of 'guidelines' (see comments in issue #32)
• The versioning and release timing will be handled and agreed per API family. This information will be captured in the README.md file included in each API Sub-Project.

[shilpa-padgaonkar]

Feedback requested by commonality members on the point "Clarify whether user stories (no.4) will be included in this deliverable, or kept internal."

[Kevsy]

I don't think user stories should be essential - an example use should be sufficient.

[Kevsy]

Another point: the criteria for API release may be different for major|minor|patch

[jordonezlucena]

@shilpa-padgaonkar, @Kevsy: as for the user stories, we already have this captured in the API proposal template. My proposal is to simply copy-paste the text there.

[shilpa-padgaonkar]

@jordonezlucena: Agree
@Kevsy @jordonezlucena :
Do we want to now change User stories criteria to optional? If we want to bring in this change now, it would again need a quorum, as done for the initial version.

[Kevsy]

@shilpa-padgaonkar I agree with @jordonezlucena - user stories can be kept mandatory, and pasted from the API proposal template.

[jordonezlucena]

Sorry guys, I misread the original comment. I mixed up "use cases" and "user stories" -- apologies.
I do see that what is in the template is use cases, not user stories.
For user stories, we already have a template agreed here. So yes, let's be stick to the original plan and keep user stories as mandatory. If we do see there's no value on bringing it as we publish new APIs, let's come back to this topic and modify it accordingly. But let's give it a try.

[shilpa-padgaonkar]

Closing Issue PR #70 merged