+1 to make the commands consistent and create an issue to track. We should evaluate a few other CLI tools too and see what is the best approach (deciding a command format and deprecating commands). A couple of "newly added commands" Wasura mentioned above are already in the pipeline for apictl 3.1.1 patch release which will release within one or two weeks' time. We should make a proper and a bit faster decision and change those commands before the patch release.
Thanks! Malintha On Thu, Apr 30, 2020 at 7:39 PM Harsha Kumara <hars...@gmail.com> wrote: > +1 for the change in the next release. @wasura @malintha shall we create a > issue and track it? > > On Fri, May 1, 2020 at 12:06 AM Bhathiya Jayasekara <bhath...@wso2.com> > wrote: > >> Yes, we can keep both formats for some time, and mention the old format >> is deprecated. It won't affect any existing users that way. We just need to >> decide when we can do this. >> >> Thanks, >> Bhathiya >> >> On Thu, Apr 30, 2020 at 6:57 PM Harsha Kumara <hars...@gmail.com> wrote: >> >>> >>> >>> On Thu, Apr 30, 2020 at 11:18 PM Uvindra Dias Jayasinha < >>> uvin...@wso2.com> wrote: >>> >>>> Ideally it would be great if we could make the commands more consistent >>>> but we need to take care about changing existing ones because we can end up >>>> breaking customers existing CI/CD flows. >>>> >>>> The commands are now a binding API. If we are changing them in the >>>> future we need to first deprecate the current ones. >>>> >>> Yes that's what I meant to decide best way to migrate our existing >>> commands later and adhere new commands to the convention. We still may have >>> the old commands in depreciated mode and do a release with the changes. We >>> can't change old commands without addressing the backward compatibility. >>> >>>> >>>> On Thu, 30 Apr 2020 at 18:10, Harsha Kumara <hars...@gmail.com> wrote: >>>> >>>>> >>>>> >>>>> On Thu, Apr 30, 2020 at 10:02 PM Wasura Wattearachchi <was...@wso2.com> >>>>> wrote: >>>>> >>>>>> Hi all, >>>>>> >>>>>> There are two (2) types of command signatures in API Controller such >>>>>> as apictl [verb] [noun] [flags] and apictl [command] [flags]. Below >>>>>> are the commands belonging to those two (2) categories. >>>>>> >>>>>> apictl [verb] [noun] [flags] >>>>>> >>>>>> apictl [command] [flags] >>>>>> >>>>>> Existing commands: >>>>>> >>>>>> - >>>>>> >>>>>> apictl list apis [flags] >>>>>> - >>>>>> >>>>>> apictl list apps [flags] >>>>>> - >>>>>> >>>>>> apictl login <env-name> [flags] >>>>>> - >>>>>> >>>>>> apictl logout <env-name> [flags] >>>>>> - >>>>>> >>>>>> apictl install api-operator [flags] >>>>>> - >>>>>> >>>>>> apictl uninstall api-operator [flags] >>>>>> - >>>>>> >>>>>> apictl change registry [flags] >>>>>> - >>>>>> >>>>>> apictl version <---- apictl noun only >>>>>> - >>>>>> >>>>>> apictl help <----- apictl verb only >>>>>> >>>>>> >>>>>> Newly added commands: >>>>>> >>>>>> - >>>>>> >>>>>> apictl list api-products [flags] >>>>>> >>>>>> Existing commands: >>>>>> >>>>>> - >>>>>> >>>>>> apictl add [flags] >>>>>> - >>>>>> >>>>>> apictl add-env [flags] >>>>>> - >>>>>> >>>>>> apictl remove-env [flags] >>>>>> - >>>>>> >>>>>> apictl export-api [flags] >>>>>> - >>>>>> >>>>>> apictl export-apis [flags] >>>>>> - >>>>>> >>>>>> apictl export-app [flags] >>>>>> - >>>>>> >>>>>> apictl import-api [flags] >>>>>> - >>>>>> >>>>>> apictl import-app [flags] >>>>>> - >>>>>> >>>>>> apictl init [flags] >>>>>> - >>>>>> >>>>>> apictl get-keys [flags] >>>>>> - >>>>>> >>>>>> apictl set [flags] >>>>>> - >>>>>> >>>>>> apictl update [flags] >>>>>> >>>>>> >>>>>> Newly added commands: >>>>>> >>>>>> - >>>>>> >>>>>> apictl delete-api [flags] >>>>>> - >>>>>> >>>>>> apictl change-api-status [flags] >>>>>> - >>>>>> >>>>>> apictl delete-api-product [flag] >>>>>> >>>>>> >>>>>> Commands to be added: >>>>>> >>>>>> - >>>>>> >>>>>> apictl import-api-product [flags] >>>>>> - >>>>>> >>>>>> apictl export-api-product [flags] >>>>>> >>>>>> >>>>>> Eventually, it would be better if we can stick into one command >>>>>> structure (which is apictl [verb] [noun] [flags]) as >>>>>> @Bhathiya Jayasekara <bhath...@wso2.com> and @Harsha Kumara >>>>>> suggested. +1 for that, since the commands will be more consistent. >>>>>> >>>>>> But Is it okay to start with the commands for API Products only (IMO, >>>>>> users will be confused if this is only done for API Products, not APIs or >>>>>> Apps) or shall we convert all the commands at once, in a future release? >>>>>> >>>>> Yes it would good if those commands become more consistent. At the >>>>> moment we should follow the proper strategy when adding new commands. We >>>>> may need to decide best way to move existing commands to a consistent >>>>> format. Having consistency will make commands less complicated. >>>>> >>>>>> >>>>>> Your opinions will be highly appreciated. >>>>>> >>>>>> Thank you! >>>>>> >>>>>> On Thu, Apr 16, 2020 at 10:13 AM Wasura Wattearachchi < >>>>>> was...@wso2.com> wrote: >>>>>> >>>>>>> Hi all, >>>>>>> >>>>>>> This is regarding the issue >>>>>>> <https://github.com/wso2/product-apim-tooling/issues/168> which >>>>>>> requests to support listing and generating tokens for API Products >>>>>>> through >>>>>>> API Controller (apictl). Currently, we do not support any functionality >>>>>>> related to API Products from API Controller side. Thus, we can introduce >>>>>>> the following four (4) functionalities as a new feature (rather than a >>>>>>> fix >>>>>>> to the above-stated issue) in order to improve API Controller, >>>>>>> additional >>>>>>> to what has been requested in the above issue. >>>>>>> >>>>>>> >>>>>>> 1. >>>>>>> >>>>>>> Import API Products >>>>>>> 2. >>>>>>> >>>>>>> Export API Products >>>>>>> 3. >>>>>>> >>>>>>> List API Products >>>>>>> 4. >>>>>>> >>>>>>> Generate keys (tokens) for API Products >>>>>>> >>>>>>> >>>>>>> Approaches >>>>>>> >>>>>>> Here, we can identify two (2) approaches for importing/exporting API >>>>>>> Products. >>>>>>> >>>>>>> Approach 1 - Import/export without the dependant APIs >>>>>>> >>>>>>> 1. >>>>>>> >>>>>>> Import API Products >>>>>>> >>>>>>> Allow to import an API Product only if the dependent APIs have been >>>>>>> already imported/created inside the API Manager. The main task here >>>>>>> is to check whether the required resources to create the API Product are >>>>>>> with the APIs in the API Manager. >>>>>>> >>>>>>> 1. >>>>>>> >>>>>>> Export API Products >>>>>>> >>>>>>> Allow to export/download an API Product without the related APIs >>>>>>> inside the archive file. >>>>>>> >>>>>>> Approach 2 - Import/export with the dependant APIs >>>>>>> >>>>>>> 1. >>>>>>> >>>>>>> Import API Products >>>>>>> >>>>>>> Give freedom to the user to import an API Product along with the >>>>>>> related APIs (archived together) only if the dependent APIs have >>>>>>> not been already imported/created inside the API Manager. If the >>>>>>> user tries to import an already imported API/APIs when importing the API >>>>>>> Product, an error should be displayed. >>>>>>> >>>>>>> 1. >>>>>>> >>>>>>> Export API Products >>>>>>> >>>>>>> Allow to export/download an API Product with the dependent APIs >>>>>>> inside the archive file. >>>>>>> >>>>>>> Comparison of Approach 1 and 2 >>>>>>> >>>>>>> Approach 1 >>>>>>> >>>>>>> Approach 2 >>>>>>> >>>>>>> - >>>>>>> >>>>>>> Advantage >>>>>>> >>>>>>> Basically our rule would be "If you need to create a CI/CD process >>>>>>> for an API Product, you should already have performed CI/CD process for >>>>>>> all >>>>>>> the dependent APIs". >>>>>>> >>>>>>> So as you can see, after doing CI/CD for each independent API you >>>>>>> will have all the required APIs imported/exported. Then you can proceed >>>>>>> with CI/CD for API Products smoothly since the required APIs have been >>>>>>> already imported/exported. (If APIs are shared between two or more API >>>>>>> Products, when importing those API Products, those shared APIs will not >>>>>>> be >>>>>>> imported/updated repeatedly, which is efficient) >>>>>>> >>>>>>> >>>>>>> - >>>>>>> >>>>>>> Disadvantage >>>>>>> >>>>>>> Manually need to setup the CI/CD flows for API Products as the tool >>>>>>> does not take care of updating the dependent APIs. >>>>>>> >>>>>>> - >>>>>>> >>>>>>> Advantage >>>>>>> >>>>>>> Easier to setup the CI/CD flows for API Products as the tool takes >>>>>>> care of updating the dependent APIs. >>>>>>> >>>>>>> >>>>>>> - >>>>>>> >>>>>>> Disadvantage >>>>>>> >>>>>>> If APIs are shared between two or more API Products, when importing >>>>>>> those API Products, those shared APIs will be imported/updated >>>>>>> repeatedly, >>>>>>> which is inefficient. >>>>>>> >>>>>>> Commands to be used >>>>>>> >>>>>>> Here, we can identify two (2) ways such as using existing commands >>>>>>> or using a new set of commands. >>>>>>> >>>>>>> Using existing commands >>>>>>> >>>>>>> 1. >>>>>>> >>>>>>> Import API Products >>>>>>> >>>>>>> Use the same command that we currently use to import an API “apictl >>>>>>> import-api”. >>>>>>> >>>>>>> 1. >>>>>>> >>>>>>> Export API Products >>>>>>> >>>>>>> Use the same command that we currently use to export an API “apictl >>>>>>> export-api”. >>>>>>> >>>>>>> Currently, name (-n) and (-v) are mandatory in the export-api >>>>>>> command. But for products, we do not have a version. So we cannot make >>>>>>> the >>>>>>> version parameter mandatory. If we do not mandate it, no issue with >>>>>>> products, but we need a way to download APIs without the version param. >>>>>>> Then we can follow the approach like: if there is only one API with >>>>>>> name:foo, we download it. But if there are multiple APIs with name:foo >>>>>>> (with multiple versions) we give an error. >>>>>>> >>>>>>> 1. >>>>>>> >>>>>>> List API Products >>>>>>> >>>>>>> List API Products along with the APIs using the existing command “apictl >>>>>>> list apis”. Further, we can improve this command by introducing a >>>>>>> flag such as --api-products which can take either true or false. If >>>>>>> true is >>>>>>> given, the API Products will be listed along with the APIs and if false >>>>>>> is >>>>>>> given, only the APIs will get listed (which is similar to the current >>>>>>> behaviour of “apictl list apis” command) not API Products. (This is >>>>>>> recommended if you choose Command 1 in both import and export as stated >>>>>>> earlier to maintain the consistency) >>>>>>> >>>>>>> 1. >>>>>>> >>>>>>> Generate keys (tokens) for API Products >>>>>>> >>>>>>> We can extend the current command “apictl get-keys” which has the >>>>>>> ability to generate keys for APIs, in a way that it will have the >>>>>>> ability >>>>>>> to generate keys for API Products as well. >>>>>>> >>>>>>> Using a new set of commands >>>>>>> >>>>>>> 1. >>>>>>> >>>>>>> Import API Products >>>>>>> >>>>>>> Introduce a new command similar to what we currently use when >>>>>>> importing an API. Example:- “apictl import-api-product”. >>>>>>> >>>>>>> 1. >>>>>>> >>>>>>> Export API Products >>>>>>> >>>>>>> Introduce a new command similar to what we currently use when >>>>>>> exporting an API. Example:- “apictl export-api-product”. >>>>>>> >>>>>>> 1. >>>>>>> >>>>>>> List API Products >>>>>>> >>>>>>> Introduce a separate command as “apictl list api-products” to list >>>>>>> API Products. >>>>>>> >>>>>>> Comparison of “Using existing commands” and “Using a new set of >>>>>>> commands” >>>>>>> >>>>>>> Using existing commands >>>>>>> >>>>>>> Using a new set of commands >>>>>>> >>>>>>> - >>>>>>> >>>>>>> Advantage >>>>>>> >>>>>>> Can be used directly in CI/CD flow without worrying about the >>>>>>> project type whether it is an API or an API Product. (Refer to the >>>>>>> disadvantage of the other column for more information) >>>>>>> >>>>>>> >>>>>>> - >>>>>>> >>>>>>> Disadvantage >>>>>>> >>>>>>> Since we are using “apictl export-api” (or “apictl import-api”) >>>>>>> there is a wording issue. >>>>>>> >>>>>>> But IMO, this is not a problem, since API Product is in fact after >>>>>>> all an API. >>>>>>> >>>>>>> - >>>>>>> >>>>>>> Advantage >>>>>>> >>>>>>> Since we have another command for importing/exporting apps as >>>>>>> import-apps/export-apps, one could naturally go for a new command for >>>>>>> import-api-product/export-api-product. >>>>>>> >>>>>>> >>>>>>> - >>>>>>> >>>>>>> Disadvantage >>>>>>> >>>>>>> In CI/CD flow this can be a bit inconvenient because APIs and API >>>>>>> Products are very similar, so would be its project structure. But from >>>>>>> the >>>>>>> automation script, it has to figure out which command to execute: >>>>>>> export-api or export-api-product (same for import as well), since it >>>>>>> does >>>>>>> not know this project is an API or an API Product. >>>>>>> >>>>>>> Your feedback to choose the appropriate approaches and commands >>>>>>> (with the problems that may arise) for each of the above tasks will be >>>>>>> much >>>>>>> appreciated. Furthermore, it would be great if new more simplified >>>>>>> approaches can be identified in addition to the above-stated approaches. >>>>>>> >>>>>>> Thank you! >>>>>>> -- >>>>>>> *Wasura Wattearachchi* | Software Engineer | WSO2 Inc. >>>>>>> (m) +94775396038 | (e) was...@wso2.com | (b) Medium >>>>>>> <https://medium.com/@wasuradananjith> >>>>>>> [image: http://wso2.com/signature] <http://wso2.com/signature> >>>>>>> >>>>>>> >>>>>>> >>>>>> >>>>>> -- >>>>>> *Wasura Wattearachchi* | Software Engineer | WSO2 Inc. >>>>>> (m) +94775396038 | (e) was...@wso2.com | (b) Medium >>>>>> <https://medium.com/@wasuradananjith> >>>>>> [image: http://wso2.com/signature] <http://wso2.com/signature> >>>>>> >>>>>> >>>>>> >>>>> >>>>> -- >>>>> *Harsha Kumara* >>>>> *PhD Student* >>>>> *LaTrobe University* >>>>> >>>> >>>> >>>> -- >>>> Regards, >>>> Uvindra >>>> >>>> Mobile: 777733962 >>>> >>> >>> >>> -- >>> *Harsha Kumara* >>> *PhD Student* >>> *LaTrobe University* >>> >> >> >> -- >> *Bhathiya Jayasekara* | Senior Technical Lead | WSO2 Inc. >> (m) +94 71 547 8185 | (e) bhathiya-@t-wso2-d0t-com >> >> >> > > -- > *Harsha Kumara* > *PhD Student* > *LaTrobe University* > -- Malintha Amarasinghe *WSO2, Inc. - lean | enterprise | middleware* http://wso2.com/ Mobile : +94 712383306
_______________________________________________ Architecture mailing list Architecture@wso2.org https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture
