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
_______________________________________________ Architecture mailing list Architecture@wso2.org https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture
