Hi all, +1 to revamp the commands in API Controller.
An issue has been created [1] regarding this and a new mail thread was created [2] to discuss and to keep track of the progress of this. All are welcome to suggest more ideas and opinions regarding this. [1] https://github.com/wso2/product-apim-tooling/issues/293 [2] Mail: [Architecture] [APIM] Revamp the commands of API Controller Thank you! On Fri, May 1, 2020 at 11:10 AM Naduni Pamudika <nad...@wso2.com> wrote: > On Thu, Apr 30, 2020 at 9:54 PM Malintha Amarasinghe <malint...@wso2.com> > wrote: > >> +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. >> >> +1. Will do the modifications to the newly added delete-api and > change-api-status commands which we are going to ship with the next patch > release. We can focus on revamping the rest of the already existing > commands for the next major release. > > Thanks, > Naduni > >> 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 >> > > > -- > *Naduni Pamudika* | Senior Software Engineer | WSO2 Inc. > (m) +94 (71) 9143658 | (w) +94 (11) 2145345 | (e) nad...@wso2.com > [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>
_______________________________________________ Architecture mailing list Architecture@wso2.org https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture
