Problem description
I understand that the API is targeted at a very specific type of API consumer - an Application Provider (aka Application Developer) who can be expected to have considerable domain knowledge around edge cloud architectures and application deployment methodologies.
However, that is no excuse for not at least providing external references for the terms used throughout the API, rather than implying "if you don't understand these terms, this API is noy for you". Providing references will help potential API consumers who understand the use case, but not the specifics of deploying their application to an edge cloud environment.
"In-band" documentation describing the API use cases and application deployment lifecycles could also be improved.
Property names used throughout the API should also be reviewed, as some of them are over-abbreviated. I understand that developers love shortening names - application becomes "app", repository becomes "repo", Kubernetes becomes "K8s", infrastructure becomes "infra" - they just can't help themselves. But CAMARA are trying to define APIs that use more inclusive language to promote adoption and at least encourage potential API consumers to proceed along the learning curve.
So review property names such as "appRepo", "appId" and "infraKind" to see if using the full name would not make it clearer as to what was required.
Also, use consistent names throughout the API - e.g. "kubernetesClusterRefs" should not become "clusterRefs" for a different endpoint. Pick a name and stick to it.
The API definition also includes unused tags - "App Instance CALLBACK Operation" and "App Deployment CALLBACK Operation".
Expected action
- Review and improve API documentation, including external references to terminology that is not otherwise defined
- Document the application deployment lifecycle properly (i.e. how would the API consumer use the API from beginning to end for a given application?)
- Review property names to see if the names can be made more "friendly"
- Remove unused tags
Additional context
None
Problem description
I understand that the API is targeted at a very specific type of API consumer - an Application Provider (aka Application Developer) who can be expected to have considerable domain knowledge around edge cloud architectures and application deployment methodologies.
However, that is no excuse for not at least providing external references for the terms used throughout the API, rather than implying "if you don't understand these terms, this API is noy for you". Providing references will help potential API consumers who understand the use case, but not the specifics of deploying their application to an edge cloud environment.
"In-band" documentation describing the API use cases and application deployment lifecycles could also be improved.
Property names used throughout the API should also be reviewed, as some of them are over-abbreviated. I understand that developers love shortening names - application becomes "app", repository becomes "repo", Kubernetes becomes "K8s", infrastructure becomes "infra" - they just can't help themselves. But CAMARA are trying to define APIs that use more inclusive language to promote adoption and at least encourage potential API consumers to proceed along the learning curve.
So review property names such as "appRepo", "appId" and "infraKind" to see if using the full name would not make it clearer as to what was required.
Also, use consistent names throughout the API - e.g. "kubernetesClusterRefs" should not become "clusterRefs" for a different endpoint. Pick a name and stick to it.
The API definition also includes unused tags - "App Instance CALLBACK Operation" and "App Deployment CALLBACK Operation".
Expected action
Additional context
None