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. 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, 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. 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 <[email protected]> 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 <[email protected]> > 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 <[email protected]> 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 <[email protected]> >>> 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 < >>>> [email protected]> wrote: >>>> >>>>> Hi Arshardh, >>>>> >>>>> On Fri, Oct 26, 2018 at 11:16 AM Arshardh Ifthikar <[email protected]> >>>>> 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: [email protected] >>>>>> Mobile: +94719806525 >>>>>> Web: http://wso2.com >>>>>> >>>>>> <http://wso2.com/signature> >>>>>> _______________________________________________ >>>>>> Architecture mailing list >>>>>> [email protected] >>>>>> 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 >>>>> [email protected] >>>>> https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture >>>>> >>>> >>>> >>>> -- >>>> *Sanjeewa Malalgoda* >>>> Software Architect | Associate Director, Engineering - WSO2 Inc. >>>> (m) +94 712933253 | (e) [email protected] | (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 >>>> [email protected] >>>> 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 >>> [email protected] >>> https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture >>> >> >> >> -- >> *Sanjeewa Malalgoda* >> Software Architect | Associate Director, Engineering - WSO2 Inc. >> (m) +94 712933253 | (e) [email protected] | (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 >> [email protected] >> 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 > [email protected] > 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 [email protected] https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture
