Skip to content
This repository has been archived by the owner on Sep 2, 2024. It is now read-only.

Complete release of an API - checklist #59

Closed
jordonezlucena opened this issue Jul 26, 2022 · 10 comments
Closed

Complete release of an API - checklist #59

jordonezlucena opened this issue Jul 26, 2022 · 10 comments
Assignees

Comments

@jordonezlucena
Copy link
Contributor

jordonezlucena commented Jul 26, 2022

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

@shilpa-padgaonkar
Copy link
Contributor

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

@jordonezlucena
Copy link
Contributor Author

jordonezlucena commented Aug 24, 2022

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
Copy link
Contributor

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

@Kevsy
Copy link
Contributor

Kevsy commented Sep 21, 2022

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

@Kevsy
Copy link
Contributor

Kevsy commented Sep 21, 2022

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

@jordonezlucena
Copy link
Contributor Author

@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
Copy link
Contributor

@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
Copy link
Contributor

Kevsy commented Sep 27, 2022

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

@jordonezlucena
Copy link
Contributor Author

jordonezlucena commented Sep 27, 2022

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
Copy link
Contributor

Closing Issue PR #70 merged

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Projects
None yet
Development

No branches or pull requests

3 participants