On Mon, Oct 29, 2018 at 9:29 PM Malintha Amarasinghe <malint...@wso2.com> wrote:
> IMO having a separate file is a better option than having everything in > the API definition. > > The API definition fully describes the "implementation details" of the > API. This contains lots of information including the descriptions, DTOs > etc. The details like throttling, CORS, backend endpoints are related to > the "managed" API. Most of the time, what developers start with is the > swagger definition of the backend API service. This does not contain any > WSO2 specific information. What they most of the time need is to create the > APIM API using the same swagger definition. If we ask them to use > extensions, the first time it would be OK; they take the backend swagger > and then add WSO2 extensions. But later the problem is merging the changes > to the APIM swagger that are added to the original (backend) swagger > definition. This is a painful operation over time. > I don't get the complexity you are explaining. If someone build the OAS in a modular fashion how can this be a problem ? The devs can start with the backend spec first as you said and then add gateway specific extensions later on. If changes happens at a later stage, you can change the contract and build the backend and the gateway with the same file. Gateway extensions will be ignored when the backend is generated. > > Also, in some of the cases, the API definition becomes huge. For example; > Open Banking related API definitions. The cause for that is, the > descriptions, models DTOs, a large set of parameters etc. But from APIM > point of view we are not interested in them much, > I don't agree with this, I think one of the issues of not having proper API docs today, is that devs don't care much in importing all the DTO models, descriptions and comments into the managed API docs. I think those are important, if you are doing a simple pass through API. > what we are actually interested is only a small part of it; for example, > host, basepath, schemes, paths etc. Adding the managed API configs inside > those huge definitions will cause readability issues. We can't easily find > the information we need by just looking at the definition which consists of > lots of unwanted (which we are not interested) details. > Again I think its about building the OAS in a modular fashion. OAS support Jason references so your OAS should not be a single long file. We can look at AWS gateway OAS usage as a ref impl - https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-swagger-extensions.html > > If we keep WSO2 related configurations separately, both of the above > problems will be resolved. > > I think we can consider both options; having a separate file vs having a > set of flags. From CI/CD perspective, I think it would be easy if we keep a > separate file. For example; the backend endpoint is currently introduced > with a flag (-e), but when we define a CI/CD flow there should be a way to > get that endpoint from somewhere and then add it to -e flag when doing the > micro-gw setup command from the CI/CD platform. If we are using Git, again > we will have to add it in a file, then read from it and append to the setup > command. If we can support loading all the APIM managed API related > information from one file, it would be easier than that. > > eg: micro-gw setup test-project -o /path/to/def/apidef.yaml > --managed-api-conf /path/to/managed/api-conf.yaml > > api-conf.yaml contains all the information like CORS configs, backend > information (including load balanced, failover), throttling information > etc. If we add anything new in future, we can add them into this file > without the need to add separate flags for each. > > Thanks! > > > On Tue, Oct 30, 2018 at 3:14 AM Nuwan Bandara <nu...@wso2.com> wrote: > >> I personally like how Jo has put it and feel thats more aligned with >> industry adoption. >> >> I think micro-gw build is something a dev will use to front his >> microservice(s) while development and when automating for test/prod they >> would integrate this to the CI/CD. So I assume the tool will be used by the >> devs as a CLI and also will be used at the CI/CD platform. >> >> If we constrain everything to one file with OAS extensions, then we can >> easily do git-ops on it. The dev experience will be great and the CI/CD >> integration will also be smooth. Devs will only have to work with one file >> and thats it. >> >> I understand NuwanD's concern too, what if someone bring a genaric >> swagger file and use that, they no ep definitions etc, as the extensions >> are custom to us. Thats true, but even if we introduce our own file to >> define WSO2 specific stuff that developer have to create that file, which >> is equal effort (only thing is its a separate file). But IMO OAS defined >> custom extensions just for this reason. I think we should take advantage of >> that. >> >> If we stick to that, the dev have to only change that file and push it >> and the system will build the gateway and deploy. >> >> Regards, >> /Nuwan >> >> On Mon, Oct 29, 2018 at 6:09 AM Sanjeewa Malalgoda <sanje...@wso2.com> >> wrote: >> >>> I think i need to explain little bit my reply. >>> >>> What i wanted to say is, we can always start with swagger file and >>> should try to only limit to information available in swagger. But when we >>> need security, throttling like QoS then apply them in simplest possible >>> way. When we move same API to managed system we can go to detailed API >>> definition. >>> >>> Thanks, >>> sanjeewa. >>> >>> On Mon, Oct 29, 2018 at 3:32 PM Joseph Fonseka <jos...@wso2.com> wrote: >>> >>>> I guess using swagger extensions can be a problem in certain contexts. >>>> Can you let me know the following >>>> >>>> 1. Who are the target audiences of this feature? Is it for API >>>> developers or devs who would be doing integrations. >>>> 2. How will this command be used, will devs run it more manually or >>>> plugged into CICD? >>>> >>>> The reason I found OAS extensions are good to capture the information >>>> is that If I am an API Developer I would be keeping API Design in an >>>> OAS file. In that case, it is quite natural to capture the throttling and >>>> security information in that file itself. Then OAS file will be committed >>>> to git and can be easily tied up to a CICD tool. So the OAS will act as an >>>> SSOT. >>>> >>>> Regards >>>> Jo >>>> >>>> >>>> >>>> >>>> >>>> On Mon, Oct 29, 2018 at 2:57 PM Sanjeewa Malalgoda <sanje...@wso2.com> >>>> wrote: >>>> >>>>> I think using swagger extension is not good idea. Reason is we cannot >>>>> ask user to add custom attributes which required for us. And most of the >>>>> time users are not willing to do that because this API definition can be >>>>> used any many different systems and teams(Ex clients, server stubs, docs >>>>> etc). They all might not interested about APIM specific attributes. If we >>>>> are to fetch API definition from OAS file and fetch other APIM specific >>>>> attributes from another source then we will have to merge them carefully. >>>>> We came a across this problem many times in recent past and its good to >>>>> avoid that if possible. >>>>> >>>>> My suggestion for this is allow minimum required security validation, >>>>> throttling etc in generated gateway(can apply to all places based on pre >>>>> defined parameter). Then let users to apply throttling + security more >>>>> granular way once we take this API to API Management system. After >>>>> developer done with initial testing they will move this API to API >>>>> Management solution. >>>>> >>>>> Thanks, >>>>> sanjeewa. >>>>> >>>>> On Sat, Oct 27, 2018 at 7:28 AM Malintha Amarasinghe < >>>>> malint...@wso2.com> wrote: >>>>> >>>>>> Hi Arshardh, >>>>>> >>>>>> On Fri, Oct 26, 2018 at 11:16 AM Arshardh Ifthikar <arsha...@wso2.com> >>>>>> wrote: >>>>>> >>>>>>> Hi all, >>>>>>> >>>>>>> The existing Microgateway loads the api via contacting the API >>>>>>> Manager instance that should be up and running. We are developing a >>>>>>> feature >>>>>>> where we have given the option to setup the Microgateway without an API >>>>>>> Manager instance running. There are two aspects that the Microgateway >>>>>>> uses >>>>>>> the API Manager during setup >>>>>>> >>>>>>> 1. Loading the Api Definition >>>>>>> 2. Fetching the Throttling Policies >>>>>>> >>>>>>> In order to decouple the the Microgateway from API Manager, these >>>>>>> aspects needs to be addressed. >>>>>>> >>>>>>> *1. Loading the Api Definition* >>>>>>> This implementation requires the user to enter at least the path of >>>>>>> the open api specification file and the endpoint of that API. If the >>>>>>> user >>>>>>> needs additional functionality, they can provide the paths to the >>>>>>> endpoint >>>>>>> definition and the CORS configuration json files. >>>>>>> >>>>>>> - The Open API Specification file should be given with the *-o * >>>>>>> or* --open-api *option. >>>>>>> - The endpoint needs to be given with the *-e* or *--endpoint* >>>>>>> option. >>>>>>> - If the user needs to give additional information on the >>>>>>> endpoint (ex: endpoint type), the user can give the path to the >>>>>>> endpoint >>>>>>> config with the *-ec* or *--endpointConfig *option. >>>>>>> - The user can provide the path to the CORS configuration with >>>>>>> the *-cc* or *--corsConfig *option. >>>>>>> >>>>>>> The following is the basic command to setup a new API in the >>>>>>> Microgateway with this feature implemented. >>>>>>> >>>>>>>> *micro-gw setup test-project -o /path/to/def/apidef.json -e >>>>>>>> http://localhost:9090/hello/sayHello >>>>>>>> <http://localhost:9090/hello/sayHello>* >>>>>>> >>>>>>> >>>>>> -o is typically used to specify the "output" location so can made a >>>>>> confusion at first glance. Shall we try to use a different flag? (eg : >>>>>> -oa) >>>>>> >>>>>> Is it possible to override the endpoint configurations you provide by >>>>>> -e or -ec after setting up and building the microgateway? Just wanted to >>>>>> make sure [1] is supported here too. >>>>>> >>>>>> [1] >>>>>> https://docs.wso2.com/display/AM260/Overriding+Endpoint+Information >>>>>> >>>>>> Thanks! >>>>>> Malintha >>>>>> >>>>>>> >>>>>>> *2. Fetching the Throttling Policies* >>>>>>> We store the most commonly used policies within the >>>>>>> Microgateway distribution and copy these policies to the project when >>>>>>> the >>>>>>> setup command is executed. If a user needs to add a custom policy, the >>>>>>> user >>>>>>> can add it to the policy directory in the Microgateway. >>>>>>> >>>>>>> Your comments and suggestions on this feature will be highly >>>>>>> appreciated. >>>>>>> >>>>>>> Thanks, >>>>>>> Arshardh >>>>>>> -- >>>>>>> *Arshardh Ifthikar* >>>>>>> Software Engineer | WSO2 Inc. >>>>>>> >>>>>>> Email: arsha...@wso2.com >>>>>>> Mobile: +94719806525 >>>>>>> Web: http://wso2.com >>>>>>> >>>>>>> <http://wso2.com/signature> >>>>>>> _______________________________________________ >>>>>>> Architecture mailing list >>>>>>> Architecture@wso2.org >>>>>>> https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture >>>>>>> >>>>>> >>>>>> >>>>>> -- >>>>>> 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 >>>>>> >>>>> >>>>> >>>>> -- >>>>> *Sanjeewa Malalgoda* >>>>> Software Architect | Associate Director, Engineering - WSO2 Inc. >>>>> (m) +94 712933253 | (e) sanje...@wso2.com | (b) Blogger >>>>> <http://sanjeewamalalgoda.blogspot.com>, Medium >>>>> <https://medium.com/@sanjeewa190> >>>>> >>>>> GET INTEGRATION AGILE <https://wso2.com/signature> >>>>> Integration Agility for Digitally Driven Business >>>>> _______________________________________________ >>>>> Architecture mailing list >>>>> Architecture@wso2.org >>>>> https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture >>>>> >>>> >>>> >>>> -- >>>> >>>> -- >>>> *Joseph Fonseka* >>>> WSO2 Inc.; http://wso2.com >>>> lean.enterprise.middleware >>>> >>>> mobile: +94 772 512 430 >>>> skype: jpfonseka >>>> >>>> * <http://lk.linkedin.com/in/rumeshbandara>* >>>> >>>> _______________________________________________ >>>> Architecture mailing list >>>> Architecture@wso2.org >>>> https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture >>>> >>> >>> >>> -- >>> *Sanjeewa Malalgoda* >>> Software Architect | Associate Director, Engineering - WSO2 Inc. >>> (m) +94 712933253 | (e) sanje...@wso2.com | (b) Blogger >>> <http://sanjeewamalalgoda.blogspot.com>, Medium >>> <https://medium.com/@sanjeewa190> >>> >>> GET INTEGRATION AGILE <https://wso2.com/signature> >>> Integration Agility for Digitally Driven Business >>> _______________________________________________ >>> Architecture mailing list >>> Architecture@wso2.org >>> https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture >>> >> >> >> -- >> >> >> *Thanks & Regards,* >> *Nuwan Bandara | Director - **Solutions Architecture, WSO2 Inc.* >> *+1 646 643 8618 | +1 650 745 2169 Ext 4212 | http://nuwanbando.com >> <http://nuwanbando.com> * >> <http://www.nuwanbando.com/> >> _______________________________________________ >> Architecture mailing list >> Architecture@wso2.org >> https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture >> > > > -- > 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 > -- *Thanks & Regards,* *Nuwan Bandara | Director - **Solutions Architecture, WSO2 Inc.* *+1 646 643 8618 | +1 650 745 2169 Ext 4212 | http://nuwanbando.com <http://nuwanbando.com> * <http://www.nuwanbando.com/>
_______________________________________________ Architecture mailing list Architecture@wso2.org https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture
