Hi Malintha,
On Wed, Nov 25, 2020 at 11:58 AM Malintha Amarasinghe <malint...@wso2.com>
wrote:
> Hi,
>
> On Tue, Nov 24, 2020 at 9:28 AM Dushani Wellappili <dusha...@wso2.com>
> 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 : dusha...@wso2.com
>> Mobile : +94779367571
>> Web : https://wso2.com/
>>
>>
>>
>
>
_______________________________________________
Architecture mailing list
Architecture@wso2.org
https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture
