Thanks Sampath. Please find some comments inline.
- *Can a given API version have multiple revisions? If yes,* Yes
- *Are we allowing users to select a revision when an API version is
created?*
As per the current discussions we haven't specifically decided whether to
allow users to select a revision when creating the API version. Most
probably when creating API Version we will be using current working
copy(revision + the current changes done on top of the revision). It seems
there is also an advantage of providing the user the ability to select a
revision when creating API revision. We will discuss this further with the
team and provide an update.
Yes it will be good to allow the user to select the revision (if there are
multiple) when creating an API version which might include new operations
so that existing consumers will not be interrupted.
Also when we have multiple revisions for an API, are we allowing the users
to explicitly set which one is the current revision?( working copy) I'm
assuming this will be available in the publisher UI.
On Wed, Nov 25, 2020 at 3:27 PM Sampath Rajapakshe <[email protected]> wrote:
> Hi,
>
> - *How do revisions work with API versions? It would be good to define
> the usage of each and how they differ. *
>
> Yes, we are going to support revisions with revisioned APIs as well.
> The difference between the API revisions and API versions is as follows,
>
> When we create an API version basically a new API is created. A new API
> UUID will be issued for the new version of the API. A new API Version can
> be used when doing a major upgrade/change to the API which might alter the
> current API Consumer implementations. So by creating a new API Version we
> can honour the existing API Consumers and do the required changes in the
> new API version.
> Ex: Altering existing API resource names
>
> When we create a revision we will be using the same API and API UUID and
> then can create multiple revisions for the same API. This can be used to
> test the changes done beforehand before making it available for API
> Consumers and provide a more efficient way to revert back to a stable
> revision in a case where the API is broken. Once reverted back to a
> previous revision publisher can deploy it to relevant runtime gateway
> environments and it will be the working copy of the API. Previously, if we
> make changes to the API from publisher and deploy, the changes will get
> reflected on the API in the devportal, but now the API creator/publisher
> has the ability to test those changes by creating a new revision and then
> deploying it to a different runtime gateway environment and verify the
> changes before making them available for devportal API consumer.
>
> - *Can a given API version have multiple revisions? If yes,* Yes
> - *Are we allowing users to select a revision when an API version
> is created?*
>
> As per the current discussions we haven't specifically decided whether to
> allow users to select a revision when creating the API version. Most
> probably when creating API Version we will be using current working
> copy(revision + the current changes done on top of the revision). It seems
> there is also an advantage of providing the user the ability to select a
> revision when creating API revision. We will discuss this further with the
> team and provide an update.
>
> - *Are we going to list all revisions of a given API version in the
> developer portal or we are going to set a single revision by default? *
>
> No, We will be listing all the revisions in the Publisher UI and in the
> Devportal we will be displaying only the working copy(revision + the
> current changes done on top of the revision)) of the API. So the devportal
> user will only see the current working deployed API just as before.
>
> Since there can be multiple runtime gateway environments which has
> different revisions deployed in each, we are introducing a field such as
> “Display on Devportal” field in Publisher Revision UI for the each
> deployment, so only the runtime gateway environment which has this field as
> “true” will be available in the Devportal for that particular API.
>
> - *Is revision_history_events going to be used to maintain a change
> log? *
>
> Yes, revision history events are kept to maintain a change log. There is a
> separate email thread(API History View in Publisher) regarding this part of
> the feature.
>
> Thanks,
> Sampath
>
>
> On Wed, Nov 25, 2020 at 1:26 PM Himasha Guruge <[email protected]> wrote:
>
>> Hi Sampath,
>>
>> Please find a couple of queries related to this feature.
>>
>> - How do revisions work with API versions? It would be good to define
>> the usage of each and how they differ.
>> - Can a given API version have multiple revisions? If yes,
>> - Are we allowing users to select a revision when an API version
>> is created?
>> - Are we going to list all revisions of a given API version in the
>> developer portal or we are going to set a single revision by default?
>> - Is revision_history_events going to be used to maintain a change
>> log?
>>
>> Thanks,
>> Himasha
>>
>> On Wed, Nov 25, 2020 at 12:54 PM Chamila Adhikarinayake <
>> [email protected]> wrote:
>>
>>>
>>>
>>> On Wed, Nov 25, 2020 at 10:28 AM Sampath Rajapakshe <[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 feature implementation
>>>> design.
>>>>
>>>> The purpose of the feature from a high level point of view is as
>>>> follows.
>>>>
>>>> API creator/publisher should be able to create an API revision(copy of
>>>> the current API state) from the current working copy of the API and should
>>>> be able to deploy that revision to multiple runtime gateway environments
>>>> and also if something breaks should be able to restore to a previous
>>>> revision.
>>>>
>>>> Therefore, the following functionalities will be provided to the API
>>>> creator/publisher.
>>>>
>>>> -
>>>>
>>>> Create/Delete revisions.
>>>> -
>>>>
>>>> Deploy revision to runtime gateway environments.
>>>> -
>>>>
>>>> Reset the current working copy to a previous revision.
>>>> -
>>>>
>>>> Can deploy a different revision to an already revision deployed
>>>> runtime gateway environment. Here, the previously deployed revision will
>>>> get un-deployed and newly selected revision will get deployed to that
>>>> particular environment. Users will be prompted for approval before this
>>>> task.
>>>> -
>>>>
>>>> Revisions are also immutable but once you revert back to a previous
>>>> revision, the user can work on top of that revision(which will be
>>>> considered as the working copy of API) and create a new revision and
>>>> then
>>>> can deploy.
>>>>
>>>>
>>>> Once a revision is created we will be storing that particular API’s
>>>> registry artifacts to a new different path inside the registry.
>>>>
>>>> For example:
>>>> /system/governance/applicationdata/apis/<API_UUID>/revisions/<REVISION_ID>/
>>>>
>>>> Any possibility of storing this revision related data in the AM_DB
>>> instead of the registry? What are the benefits we get when we store it in
>>> the registry?
>>>
>>> As per the initial discussion, the proposed database structure to cater
>>>> above requirements is as follows,
>>>>
>>>>
>>>> Key Points are as follows,
>>>>
>>>>
>>>>
>>>> -
>>>>
>>>> ID and API_UUID are composite primary key for AM_REVISION table.
>>>>
>>>> Ex:
>>>>
>>>> ID= 1, API_UUID = 12345
>>>>
>>>> ID= 2, API_UUID = 12345
>>>>
>>>> ID=1, API_UUID = 98765
>>>>
>>>>
>>>> -
>>>>
>>>> Single API can have multiple revisions.
>>>> -
>>>>
>>>> One revision should be able to be deployed to multiple runtime
>>>> deployments.
>>>> -
>>>>
>>>> REVISION_UUID is the registry revisioned API artifacts ID.
>>>> -
>>>>
>>>> DISPLAY_ON_DEVPORTAL field is a flag to keep track of which runtime
>>>> deployment to be shown on the devportal.
>>>> -
>>>>
>>>> REVISION_ID field in AM_DEPLOYMENT_REVISION_MAPPING table refers to
>>>> the composite primary key(ID and API_UUID) in AM_REVISION table.
>>>> -
>>>>
>>>> The REVISION_ID field in the AM_REVISION_HISTORY_EVENTS table
>>>> refers to the composite primary key(ID and API_UUID) in the AM_REVISION
>>>> table.
>>>> -
>>>>
>>>> One revision can have multiple related revision history events.
>>>>
>>>>
>>>> Also tables such as below which keep data related to API will be
>>>> changed accordingly to keep revision details by adding a revision id field.
>>>>
>>>> URL Mapping, AM_GRAPHQL_COMPLEXITY, AM_CERTIFICATE_METADATA,
>>>> AM_API_CLIENT_CERTIFICATE
>>>>
>>>> Appreciate your inputs on the current proposed database table structure.
>>>>
>>>> Thanks,
>>>>
>>>> Sampath
>>>>
>>>> --
>>>>
>>>> *Sampath Rajapakse* | Software Engineer | WSO2 Inc.
>>>>
>>>> +94717313761 | [email protected]
>>>>
>>>>
>>>>
>>>
>>> --
>>> Regards,
>>> Chamila Adhikarinayake
>>> WSO2, Inc.
>>> Mobile - +94712346437
>>> Email - [email protected]
>>> Blog - http://helpfromadhi.blogspot.com/
>>> _______________________________________________
>>> Architecture mailing list
>>> [email protected]
>>> https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture
>>>
>>
>>
>> --
>> Himasha Guruge
>> Associate Lead Solutions Engineer - Solutions Architecture
>> WS*O2* *Inc.*
>> Mobile: +94 777459299
>> [email protected]
>> <http://wso2.com/signature>
>>
>
>
> --
>
> *Sampath Rajapakse* | Software Engineer | WSO2 Inc.
>
> +94717313761 | [email protected]
>
>
>
--
Himasha Guruge
Associate Lead Solutions Engineer - Solutions Architecture
WS*O2* *Inc.*
Mobile: +94 777459299
[email protected]
<http://wso2.com/signature>
_______________________________________________
Architecture mailing list
[email protected]
https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture
