Hi, According to the discussion, there are concerns of making a published API editable. As Chamin, Shani suggested we can get over this by clearly defining what fields we make editable. But that itself is an additional complexity we are introducing and we have to book-keep on new fields we introduce thereafter. But this would be the way to go if we are allowing this.
IMO we shouldn't allow users to do something wrong just because most users want to do it. I think we should enforce the best practice on users via our design so that they will have to follow it without choice. quoting from the swagger article Shani pointed out "A published API definition is a stable version ready for consuming from client applications. It is not supposed to be changed, and any changes will be introduced as a new version of the API." On Fri, Mar 31, 2017 at 3:45 PM, Chamin Dias <cham...@wso2.com> wrote: > Hi, > > I think we need to carefully identify the fields that we are going to make > editable, if we are going to support this. Think of an example where a > consumer is using a particular API (based on his roles). If we change the > eligible role list for that API (i.e - visible roles), then some of the > earlier consumers might loose their existing subscription after > re-publishing the API. So IMAO, I think we need to first identify what are > the things that can be edited after publishing an API. > > Thanks. > > On Fri, Mar 31, 2017 at 12:41 PM, Shani Ranasinghe <sh...@wso2.com> wrote: > >> Hi, >> >> I don't think we should allow the API to be edited once it is published. >> If there is a bug in the API , then it should be fixed and released as a >> new version IMO. I was referring to this [1]. And they say that "Publishing >> is a way to show that the API is in a stable state and its endpoints can be >> reliably called from other applications." And I agree with this too. >> This is the general perception towards a published API. >> >> But if we must support it, then shall we simply change our state name >> "CREATED" to "UNPUBLISHED" like what [1] uses. Then it wouldn't create >> confusions. >> >> Or else, we could allow them to edit the published api by bringing it >> back to the created/unpublished LC state but we control what fields they >> will be able to change without creating a new version? We will have to >> think what fields, if changed would not need to have a new version of an >> API. If they want to change any other field they HAVE to go for a new API >> version. >> [1] https://app.swaggerhub.com/help/apis/publishing-api >> >> On Fri, Mar 31, 2017 at 10:50 AM, Prasanna Dangalla <prasa...@wso2.com> >> wrote: >> >>> Hi All, >>> >>> On Fri, Mar 31, 2017 at 7:00 AM Chamalee De Silva <chama...@wso2.com> >>> wrote: >>> >>>> Hi, >>>> Agree with Raj and Nuwan. >>>> >>>> But considering the user PoV, >>>> In a situation where we change state of an Published API to maintenance >>>> state, make the change and published back, >>>> what if the subscriber is not happy with the updates which makes to the >>>> Published API ? (Assume that the changes are some technical information and >>>> not merely a bug fix). >>>> >>>> >>>> Because subscriber is not knowing what will be the change that will >>>> happen to the API. >>>> Adding to what Sajith has pointed out, >>>> I also think there should be a proper notification mechanism and *also* >>>> there should be a way of handling this user experience issue as well. >>>> >>>> >>>> >>>> Thanks, >>>> Chamalee >>>> >>>> >>>> >>>> On Fri, Mar 31, 2017 at 10:10 AM, Rajkumar Rajaratnam < >>>> rajkum...@wso2.com> wrote: >>>> >>>> I completely agree with Nuwan. We should support updating published API >>>> without increasing the version. Think about a banking industry. If there is >>>> a critical bug in the mediation logic (lets say a masking logic), they >>>> should be able to fix the issue in the same version transparently without >>>> even letting customer know that there is a bug. Publishing a minor version >>>> with a minor backward compatible fix and asking customers to update their >>>> app to call latest minor version is not an option for these kind of >>>> industries. >>>> >>>> Another example, what if we want to make some minor changes in API >>>> documentation? New API release for this kind of scenario is an over kill. >>>> >>>> Thanks. >>>> >>>> On Fri, Mar 31, 2017 at 12:04 AM Nuwan Dias <nuw...@wso2.com> wrote: >>>> >>>> Hi Malintha, >>>> >>>> Yes, the workflow you have mentioned is the same one I'm proposing too. >>>> My only concern is on a new state, because implementing that is a bit >>>> complicated and this particular use case is not very common and therefore >>>> there's little ROI :). >>>> >>>> Let's say we call this new state "MAINTENANCE", what's the difference >>>> between bringing an API to "MAINTENANCE" vs "CREATED"? If we bring an API >>>> to "MAINTENANCE", does it mean that there is a copy of the API left which >>>> is in "PUBLISHED" state? >>>> >>>> @Fazlan, in theory it is true that updating a published API is wrong. >>>> But in practice it sometimes happens because not everyone adheres to the >>>> best practices 100% always. Users may opt to make backwards compatible >>>> changes on the same minor version and some users don't even use minor >>>> versions at all. So forcing to create a new version of the API and forcing >>>> their clients to move to the newer version always is a bit too restrictive >>>> IMO >>>> >>>> >>> Yes this is what my idea as well. +1 for the notification mecanism too. >>> But I have a doubt about how we garntee that doing a change will not affect >>> the existing API functionality? >>> >>> Thanks >>> Prasanna >>> >>>> . >>>> >>>> Thanks, >>>> NuwanD. >>>> >>>> On Fri, Mar 31, 2017 at 8:41 AM, Rukshan Premathunga <ruks...@wso2.com> >>>> wrote: >>>> >>>> Hi malintha, >>>> >>>> in c5 we decided to keep in the gateway even in the create state for >>>> purpose of creator's testing. >>>> so this will be fine. but keeping additional info in the create state >>>> not something good. because create state is the state very first state when >>>> an api is create. >>>> >>>> because of that I'm +1 for additional state. >>>> >>>> Thanks and Regards >>>> >>>> On Mar 31, 2017 8:10 AM, "Malintha Amarasinghe" <malint...@wso2.com> >>>> wrote: >>>> >>>> Hi Nuwan, >>>> >>>> On Fri, Mar 31, 2017 at 12:12 AM, Nuwan Dias <nuw...@wso2.com> wrote: >>>> >>>> Hi Pubudu, >>>> >>>> The API will reside on the Gateway irrespective of its state. So this >>>> action doesn't interrupt existing subscribers or existing consumers of the >>>> API. It only prevents any new subscribers from seeing the API on the store >>>> until republished. >>>> >>>> I have thought about introducing a new LC state as well. But that only >>>> doesn't solve this issue. We need to build a mechanism to make a copy of >>>> the API and store the developer's changes elsewhere until a publisher >>>> approves the changes. Building that whole workflow is non trivial and >>>> leaves a lot more to think about as well. Besides, the above usecase is not >>>> standard practice since its not a good idea to make technical changes to >>>> published APIs. But the reality is that the real world needs it and hence >>>> we need to support it. >>>> >>>> If we are allowing this, I also feel a need of a new lifecycle state. >>>> Because, in usual CREATED state, we do not allow the API to reside in >>>> Gateway. But in *this* CREATED state, we are allowing the API to reside in >>>> Gateway (which is the API with previous details). >>>> >>>> Let me summerise the complete flow, just to double check my >>>> understanding. >>>> >>>> 1. An API is in Published state. >>>> 2. A Developer wants to make some technical changes to the API. >>>> 3. Publisher makes the API Created state (or some new state). >>>> >>>> Now the API is not visible on Store, but existing subscriptions are >>>> still valid. >>>> >>>> The previous API is available on GW, so existing invocations are >>>> working without any issue. (This, we did not allow in CREATED state in C4) >>>> >>>> 4. Developer makes changes to the API >>>> 5. Publisher accepts the changes (which means the API's lifecycle is >>>> changed to Published) >>>> 6. New changes are updated on the GW. >>>> >>>> >>>> Thanks! >>>> Malintha >>>> >>>> >>>> Thanks, >>>> NuwanD. >>>> >>>> On Thu, Mar 30, 2017 at 11:52 PM, Pubudu Gunatilaka <pubu...@wso2.com> >>>> wrote: >>>> >>>> Hi Nuwan, >>>> >>>> AFAIU, in this case, we are not addressing the original issue. Original >>>> issue here is changes made by API developers should not be reflected in >>>> Store and Gateway unless the API publisher publishes the API again. Please >>>> correct me if I am wrong. >>>> >>>> I don't think temporarily removing the API is the best solution if it >>>> is already serving requests. >>>> >>>> What if we introduce another life cycle state and transfer the API to >>>> that state until API publisher re-publishes the API. In this way, there is >>>> no effect to the existing API. >>>> >>>> Thank you! >>>> >>>> On Thu, Mar 30, 2017 at 11:41 PM, Rukshan Premathunga <ruks...@wso2.com >>>> > wrote: >>>> >>>> Hi Nuwan, >>>> >>>> If we demote API back to create, state how we are going to handle >>>> subscription already have? Are we going to disable them till the API get >>>> publish again? >>>> >>>> Also can we introduce or use the existing state to allow the API to be >>>> update without un-publishing it. once it is done we can publish it again >>>> with the changes. Because in if we demote to create state, we cannot have >>>> subscription information right? >>>> >>>> Thanks and Regards >>>> >>>> On Thu, Mar 30, 2017 at 11:15 PM, Nuwan Dias <nuw...@wso2.com> wrote: >>>> >>>> Hi, >>>> >>>> On API Manager, API Developers (!= publishers) aren't able to publish >>>> an API to the Store or Gateway. But on API Manager version 2.1.0 and >>>> before, if an API Developer makes an update to an API that is already >>>> published, the changes made by the developer are immediately reflected on >>>> the Store and Gateway. This kind of beats the purpose of preventing API >>>> Developers from publishing APIs to the Store and Gateway directly. >>>> >>>> For API Manager 3.0.0, I suggest that we prevent the API being updated >>>> by API Developers after the API has gone beyond the "CREATED" state. API >>>> Publishers should still be allowed to make updates to the fields they are >>>> eligible for (non technical information). If someone badly needs to update >>>> technical information of a published API, they should first bring the API >>>> to the "CREATED" state, which will make the API disappear temporarily and >>>> bring it back to "PUBLISHED" once the changes are saved. >>>> >>>> Thanks, >>>> NuwanD. >>>> >>>> -- >>>> Nuwan Dias >>>> >>>> Software Architect - WSO2, Inc. http://wso2.com >>>> email : nuw...@wso2.com >>>> Phone : +94 777 775 729 <+94%2077%20777%205729> >>>> >>>> >>>> >>>> >>>> -- >>>> Rukshan Chathuranga. >>>> Software Engineer. >>>> WSO2, Inc. >>>> >>>> _______________________________________________ >>>> Dev mailing list >>>> Dev@wso2.org >>>> http://wso2.org/cgi-bin/mailman/listinfo/dev >>>> >>>> >>>> >>>> >>>> -- >>>> *Pubudu Gunatilaka* >>>> Committer and PMC Member - Apache Stratos >>>> Software Engineer >>>> WSO2, Inc.: http://wso2.com >>>> mobile : +94774078049 <%2B94772207163> >>>> >>>> >>>> >>>> >>>> -- >>>> Nuwan Dias >>>> >>>> Software Architect - WSO2, Inc. http://wso2.com >>>> email : nuw...@wso2.com >>>> Phone : +94 777 775 729 <+94%2077%20777%205729> >>>> >>>> _______________________________________________ >>>> Dev mailing list >>>> Dev@wso2.org >>>> http://wso2.org/cgi-bin/mailman/listinfo/dev >>>> >>>> >>>> >>>> >>>> -- >>>> Malintha Amarasinghe >>>> Software Engineer >>>> *WSO2, Inc. - lean | enterprise | middleware* >>>> http://wso2.com/ >>>> >>>> Mobile : +94 712383306 <+94%2071%20238%203306> >>>> >>>> _______________________________________________ >>>> Dev mailing list >>>> Dev@wso2.org >>>> http://wso2.org/cgi-bin/mailman/listinfo/dev >>>> >>>> >>>> >>>> >>>> -- >>>> Nuwan Dias >>>> >>>> Software Architect - WSO2, Inc. http://wso2.com >>>> email : nuw...@wso2.com >>>> Phone : +94 777 775 729 <+94%2077%20777%205729> >>>> _______________________________________________ >>>> Dev mailing list >>>> Dev@wso2.org >>>> http://wso2.org/cgi-bin/mailman/listinfo/dev >>>> >>>> -- >>>> Rajkumar Rajaratnam >>>> Committer & PMC Member, Apache Stratos >>>> Senior Software Engineer, WSO2 >>>> >>>> LinkedIn: https://lk.linkedin.com/in/rajuu >>>> Mobile: +1 408 791 7640 <(408)%20791-7640> >>>> Blogs: http://wso2tech.blogspot.com/ | https://medium.com/@wso2tech >>>> >>>> _______________________________________________ >>>> Dev mailing list >>>> Dev@wso2.org >>>> http://wso2.org/cgi-bin/mailman/listinfo/dev >>>> >>>> >>>> >>>> >>>> -- >>>> Thanks & Regards, >>>> >>>> *Chamalee De Silva* >>>> Software Engineer >>>> *WS**O2* Inc. :http://wso2.com/ >>>> >>>> Office :- *+94 11 2145345 <%2B94%2011%202145345>* >>>> mobile :- *+94 7 <%2B94%2077%202782039>1 4315942* >>>> >>>> _______________________________________________ >>>> Dev mailing list >>>> Dev@wso2.org >>>> http://wso2.org/cgi-bin/mailman/listinfo/dev >>>> >>> -- >>> *Prasanna Dangalla* >>> Senior Software Engineer, WSO2, Inc.; http://wso2.com/ >>> lean.enterprise.middleware >>> >>> >>> *cell: +94 718 11 27 51* >>> *twitter: @prasa77* >>> >>> _______________________________________________ >>> Dev mailing list >>> Dev@wso2.org >>> http://wso2.org/cgi-bin/mailman/listinfo/dev >>> >>> >> >> >> -- >> Thanks and Regards >> *,Shani Ranasinghe* >> Senior Software Engineer >> WSO2 Inc.; http://wso2.com >> lean.enterprise.middleware >> >> mobile: +94 77 2273555 <+94%2077%20227%203555> >> Blog: http://waysandmeans.blogspot.com/ >> linked in: lk.linkedin.com/pub/shani-ranasinghe/34/111/ab >> >> _______________________________________________ >> Dev mailing list >> Dev@wso2.org >> http://wso2.org/cgi-bin/mailman/listinfo/dev >> >> > > > -- > Chamin Dias > Mobile : +94 (0) 716 097455 <%2B94%20%280%29%20773%20451194> > Email : cham...@wso2.com > LinkedIn : https://www.linkedin.com/in/chamindias > > > _______________________________________________ > Dev mailing list > Dev@wso2.org > http://wso2.org/cgi-bin/mailman/listinfo/dev > > -- Thanks & Regards, Fazlan Nazeem *Software Engineer* *WSO2 Inc* Mobile : +94772338839 <%2B94%20%280%29%20773%20451194> fazl...@wso2.com
_______________________________________________ Dev mailing list Dev@wso2.org http://wso2.org/cgi-bin/mailman/listinfo/dev
