Hi Ishara, On Thu, Nov 26, 2020 at 12:40 PM Ishara Cooray <[email protected]> wrote:
> Hi Dushani, > > Recording historical events will help for troubleshooting as well. > In that case, storing information such as > CRUD and deploy/undeploy operations on APIs along with users, requests, > responses, timestamp would be helpful. > > Hope we are planning to implement this separately for API Products as well. > Yes > > For how long do we plan to keep this data in the database? > >From code level there are no plans yet to purge the data, if the users want they can manually purge them from a script. > > > Thanks & Regards, > Ishara Cooray > Associate Technical Lead > Mobile : +9477 262 9512 > > WSO2, Inc. | http://wso2.com/ > https://wso2.com/signature > Lean . Enterprise . Middleware > > > On Wed, Nov 25, 2020 at 9:03 PM Dushani Wellappili <[email protected]> > wrote: > >> Hi Malintha, >> On Wed, Nov 25, 2020 at 11:58 AM Malintha Amarasinghe <[email protected]> >> wrote: >> >>> Hi, >>> >>> On Tue, Nov 24, 2020 at 9:28 AM Dushani Wellappili <[email protected]> >>> wrote: >>> >>>> Hi all, >>>> >>>> We are planning to add the feature in $subject to the next API-M >>>> release and this is to initiate a discussion on deciding the viable feature >>>> design. API History View feature is mainly useful for API developers to go >>>> back and see what has been changed on the particular API since it was >>>> created. This will be a *read-only view *inside the Publisher Portal. >>>> Following are the main user stories for the feature. >>>> >>>> - User(I) wants to find out what has happened/what are the >>>> operations that have executed on this API. This will show a timeline >>>> view >>>> to show a series of events that happened since the creation of this API. >>>> - User(I) wants to sort the history by time and/or filter history >>>> events by their types to find the history element that the user is >>>> looking >>>> for. >>>> >>>> As we are going to introduce the "revision support for APIs" feature >>>> along with the next release, we have *two design options *for the >>>> history view. >>>> >>>> *1. Show different history hierarchies for different revisions* >>>> >>>> >>>> >>>> >>>> In this case, when a user selects a revision (Eg: Revisions_1), all the >>>> events that happened till that revision_1 will be shown. This even includes >>>> events where prior revisions were created and restored. >>>> >>>> [image: image.png] >>>> >>>> This shows all the history up to the selected revision_3 including the >>>> reverted changes (since we have restored to a previous revision_1 in the >>>> middle). Hence, for a user who is trying to get a list of changes gone only >>>> for revision_3 of an API, they need to consciously discard such reverted >>>> changes done (Eg: PUT /apis) in the middle. >>>> >>>> *2. Show all the historical events in one hierarchy since API creation. >>>> No different views for different revisions.* >>>> >>>> [image: image.png] >>>> This includes all the events that occurred for the current working copy >>>> including both revision created, restored operations. >>>> >>>> The Publisher REST API for History View will only include one resource, >>>> *GET >>>> /apis/{apiId}/history* or *GET >>>> /apis/{apiId}/history?revision={revision_key}* returning an API >>>> History response with all the events. This may also include query >>>> parameters to filter based on timestamp or event type. >>>> >>>> There are* two options* for backend implementation for this feature to >>>> capture and persist each and every API event. >>>> >>>> *1. REST API Layer Interceptor.* >>>> This will make sure all the events are captured as they all will be >>>> done through REST APIs. However, this will tightly couple the >>>> implementation with CXF and the event details which can be captured during >>>> this stage will be more generic. (This might fail to capture depending API >>>> update events when a default version of an API is changed) >>>> >>>> *2. In Implementation Layer inside a common component where events are >>>> fired* >>>> There will be no direct coupling with the REST APIs and we could be >>>> able to capture more granular level events. This could be done in the same >>>> component logic where now events are fired. >>>> >>> >>> For the backend implementation I think we can also go for a combined >>> approach of the above two. >>> >>> Implementing the 1st one is relatively easy and we can capture about 95% >>> of the cases from that. The rest of the 5% includes cases where updating a >>> certain API causes updating another one or more APIs internally. Eg: like >>> Dushani mentioned the default version case, and publishing an API with >>> "Deprecate older versions" where few other APIs get updated. Implementing >>> everything in the implementation layer might need tweaks in many places. >>> Hence capturing those one or two edge cases in the implementation layer and >>> capturing the rest in the REST API layer should also get the work done >>> faster and in a relatively less effort. >>> >>> If the effort of doing everything in impl layer is not major, we can >>> take that approach first because that is cleaner, extensible and we can get >>> more control over it. But before doing it, we have to improve our existing >>> eventing model/framework to capture all the API events and use it as an >>> extension to implement the history table event capturing. Then the eventing >>> model/framework we build/improve will be very useful for our future >>> implementations as well. >>> >> Agree on both cases. Option1 seems less effort at the moment compared to >> the amount of code refactoring with option2. However, if we go with the >> option1 of having an interceptor, we should keep a reserved set of REST API >> operations which we should only capture right? For example, we are not >> persisting the GET /apis, GET /documents events occurring in between API >> updates, etc. Also, some REST API operations may include more than one >> main operation on the backend. (For example, update API thumbnail REST API >> includes, thumbnail resource file addition and API update both). IMO, if we >> are going for a combined approach we may need to properly decide the >> granularity of the events we are capturing as historical events. >> >> Another concern of me is, for the historic event, would it be enough if >> it only has a basic event action/description (Ex: Update API), or does it >> need to have the payload (updating API payload) as well? >> >> >>> >>> Thanks >>> Malintha >>> >>> >>>> The persistence layer for API history includes one table. >>>> >>>> *API_HISTORY_EVENTS* >>>> EVENT_ID INTEGER NOT NULL AUTOINCREMENT, >>>> EVENT_CREATED TIMESTAMP DEFAULT 0, >>>> EVENT_DESCRIPTION VARCHAR(255) NOT NULL, >>>> REVISION_KEY VARCHAR(255), >>>> PRIMARY_KEY (EVENT_ID), >>>> FOREIGN KEY (REVISION_KEY) REFERENCES API_REVISION(REVISION_KEY) >>>> >>>> Here the REVISION_KEY relates to the PK of the table where we persist >>>> revision metadata and, the revision key will be persisted only for events >>>> where revisions were created (POST /revisions). If option1 is selected >>>> (different hierarchies for different revisions), the events for that >>>> revision will be selected by querying all the rows which are less than the >>>> EVENT_ID of that particular "revision creation" event (POST /revisions). >>>> >>>> Appreciate your response on deciding the most viable options for UI >>>> design and backend implementation. >>>> >>>> Thanks. >>>> *Dushani Wellappili* >>>> Senior Software Engineer - WSO2 >>>> >>>> Email : [email protected] >>>> Mobile : +94779367571 >>>> Web : https://wso2.com/ >>>> >>>> >>>> >>> >>> _______________________________________________ >> Architecture mailing list >> [email protected] >> https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture >> >
_______________________________________________ Architecture mailing list [email protected] https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture
