How to recover accidentally deprecated/retired APIs

API Lifecycle Change — WSO2 API Manager

Hello Geeks!!! 😊😊😊

Today, I’ll explain how to recover accidentally deprecated or retired APIs on the WSO2 API Manager. 🤓🤓🤓

As you know, WSO2 API Manager is the world’s leading open-source, enterprise-grade API management platform for on-premises, cloud, and hybrid architectures.

When comes to the API lifecycle, if the API moves to the DEPRECATED state, the only option is to RETIRE it. There is no way to move the API from either the DEPRECATED or RETIRED state to a different state directly.

But, if you need to get the same API back to the deployment from the DEPRECATED or RETIRED states because of some business needs or accidentally moved to those states, how do you do that??? 🧐🧐🧐

OK. Let’s do a quick hack like a BOSS 😎😎😎

For this use case, we can use any APIM version from 3.0.0 onwards.

When comes to the API Manager 4.2.0 and above versions, we have to do the changes through the admin portal. But for the below versions, we have to do changes via the carbon management console. However, I’ll explain both ways to achieve this. 😇😇😇

• Download the WSO2 API Manager distribution through the official link [1].

Also if you have a valid WSO2 subscription, then you can download the latest updates to the product by using the update 2.0 channel. For more information, please refer to the documentation [2]

• Unzip it and start the API Manager server.

From APIM 4.2.0 and onwards

• Log into the admin portal.
• Select Advanced tab on the left navigation menu.
• By default, LifeCycle configuration doesn’t appear in the advanced configurations JSON content. To view the default lifecycle configurations, type LifeCycle and select LifeCycle autosuggested option.

Autosuggesting — WSO2 API Manager

• Then you can see a JSON content as below.

"LifeCycle": {
  "States": [
   {
    "Transitions": [
     {
      "Target": "Published",
      "Event": "Publish"
     },
     {
      "Target": "Prototyped",
      "Event": "Deploy as a Prototype"
     }
    ],
    "State": "Created",
    "CheckItems": [
     "Deprecate old versions after publishing the API",
     "Requires re-subscription when publishing the API"
    ]
   },
   {
    "Transitions": [
     {
      "Target": "Published",
      "Event": "Publish"
     },
     {
      "Target": "Created",
      "Event": "Demote to Created"
     },
     {
      "Target": "Prototyped",
      "Event": "Deploy as a Prototype"
     }
    ],
    "State": "Prototyped",
    "CheckItems": [
     "Deprecate old versions after publishing the API",
     "Requires re-subscription when publishing the API"
    ]
   },
   {
    "Transitions": [
     {
      "Target": "Blocked",
      "Event": "Block"
     },
     {
      "Target": "Prototyped",
      "Event": "Deploy as a Prototype"
     },
     {
      "Target": "Created",
      "Event": "Demote to Created"
     },
     {
      "Target": "Deprecated",
      "Event": "Deprecate"
     },
     {
      "Target": "Published",
      "Event": "Publish"
     }
    ],
    "State": "Published"
   },
   {
    "Transitions": [
     {
      "Target": "Deprecated",
      "Event": "Deprecate"
     },
     {
      "Target": "Published",
      "Event": "Re-Publish"
     }
    ],
    "State": "Blocked"
   },
   {
    "Transitions": [
     {
      "Target": "Retired",
      "Event": "Retire"
     }
    ],
    "State": "Deprecated"
   },
   {
    "State": "Retired"
   }
  ]
 },

• If you check the above content, you can see 2 states named Deprecated and Retired. When comparing the Transitions content under those states, the Retired state does not have any transitions and the Deprecated state only has the Retire transition event.

{
  "Transitions":[
      {
        "Target":"Retired",
        "Event":"Retire"
      }
  ],
  "State":"Deprecated"
},

{
  "State":"Retired"
}

So let’s change this to achieve the requirement.😁😁😁

• Under the Retired state, we need to add the Transitions content with the Re-Publish event to move the API from the RETIRED state to the PUBLISHED state.

{
    "Transitions":[
        {
          "Target":"Published",
          "Event":"Re-Publish"
        }
    ],
    "State":"Retired"
}

• Under the Deprecated state, we need to add a transition with the Re-Publish event to move the API from the DEPRECATED state to the PUBLISHED state.

{
    "Transitions":[
        {
          "Target":"Retired",
          "Event":"Retire"
        },
        {
          "Target":"Published",
          "Event":"Re-Publish"
        }
    ],
    "State":"Deprecated"
}

• After applying those changes, we need to save the content by clicking on the Save button at the bottom of the page.

That’s it!!! Now let’s check the behavior. 🤩🤩🤩

• Go to the publisher portal again and select a retired API.
• Click on the Lifecycle on the left navigation menu.
• Now you can see the Re-Publish button to move the API from the RETIRED state to the PUBLISHED state.

RETIRED the API— WSO2 API Manager

• When clicking on that, the API will move to the PUBLISHED state as below.

Re-publish the API — WSO2 API Manager

• Since we have added the Re-Publish option to the DEPRECATED state, we can see the Re-Publish button as the below image if the API is in the DEPRECATED state.

DEPRECATED the API — WSO2 API Manager

• Once we click on the Re-Publish button, the API will move to the PUBLISHED state again as below.

Re-publish the API — WSO2 API Manager

So now we have configured a way to recover the API from Depreated/Retired to Published state in APIM 4.2.0 and above versions. For more information regarding the API Lifecycle customizations, please refer to the documentation [3].

Let’s configure the same solution for below APIM 4.2.0 versions. 😇😇😇

Below APIM 4.2.0 version

• Start the API Manager server.
• Log into the carbon management console.
• Select the Extensions side tab and then click on the Lifecycles option.

Extensions — WSO2 API Manager

• Click on the View/Edit button under the APILifeCycle section.

Edit the API Lifecycle — WSO2 API Manager

• You can see an XML content as below with the API lifecycle transitions and states.

<!--
 ~ Copyright (c) 2015, WSO2 Inc. (http://www.wso2.org) All Rights Reserved.
 ~
 ~ WSO2 Inc. licenses this file to you under the Apache License,
 ~ Version 2.0 (the "License"); you may not use this file except
 ~ in compliance with the License.
 ~ You may obtain a copy of the License at
 ~
 ~    http://www.apache.org/licenses/LICENSE-2.0
 ~
 ~ Unless required by applicable law or agreed to in writing,
 ~ software distributed under the License is distributed on an
 ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 ~ KIND, either express or implied.  See the License for the
 ~ specific language governing permissions and limitations
 ~ under the License.
 -->
<aspect name="APILifeCycle" class="org.wso2.carbon.governance.registry.extensions.aspects.DefaultLifeCycle">
    <configuration type="literal">
        <lifecycle>
            <scxml xmlns="http://www.w3.org/2005/07/scxml"
                   version="1.0"
                   initialstate="Created">

                <state id="Created">
                    <datamodel>

                        <data name="checkItems">
                            <item name="Deprecate old versions after publishing the API" forEvent="">
                            </item>
                            <item name="Requires re-subscription when publishing the API" forEvent="">
                            </item>
                        </data>

                        <data name="transitionExecution">
                            <execution forEvent="Deploy as a Prototype"
                                       class="org.wso2.carbon.apimgt.impl.executors.APIExecutor">
                            </execution>
                            <execution forEvent="Publish"
                                       class="org.wso2.carbon.apimgt.impl.executors.APIExecutor">
                            </execution>
                        </data>
                    </datamodel>
                    <transition event="Publish" target="Published"/>
                    <transition event="Deploy as a Prototype" target="Prototyped"/>

                </state>

                <state id="Prototyped">
                    <datamodel>
                        <data name="checkItems">
                            <item name="Deprecate old versions after publishing the API" forEvent="">
                            </item>
                            <item name="Requires re-subscription when publishing the API" forEvent="">
                            </item>
                        </data>

                        <data name="transitionExecution">
                            <execution forEvent="Publish"
                                       class="org.wso2.carbon.apimgt.impl.executors.APIExecutor">
                            </execution>
                            <execution forEvent="Demote to Created"
                                       class="org.wso2.carbon.apimgt.impl.executors.APIExecutor">
                            </execution>
                        </data>
                    </datamodel>
                    <transition event="Publish" target="Published"/>
                    <transition event="Demote to Created" target="Created"/>
                    <transition event="Deploy as a Prototype" target="Prototyped"/>
                </state>


                <state id="Published">

                    <datamodel>

                        <data name="transitionExecution">
                            <execution forEvent="Block"
                                       class="org.wso2.carbon.apimgt.impl.executors.APIExecutor">
                            </execution>
                            <execution forEvent="Deprecate"
                                       class="org.wso2.carbon.apimgt.impl.executors.APIExecutor">
                            </execution>
                            <execution forEvent="Demote to Created"
                                       class="org.wso2.carbon.apimgt.impl.executors.APIExecutor">
                            </execution>
                            <execution forEvent="Deploy as a Prototype"
                                       class="org.wso2.carbon.apimgt.impl.executors.APIExecutor">
                            </execution>
                            <execution forEvent="Publish"
                                       class="org.wso2.carbon.apimgt.impl.executors.APIExecutor">
                            </execution>

                        </data>
                    </datamodel>
                    <transition event="Block" target="Blocked"/>
                    <transition event="Deploy as a Prototype" target="Prototyped"/>
                    <transition event="Demote to Created" target="Created"/>
                    <transition event="Deprecate" target="Deprecated"/>
                    <transition event="Publish" target="Published"/>
                </state>

                <state id="Blocked">
                    <datamodel>
                        <data name="transitionExecution">
                            <execution forEvent="Re-Publish"
                                       class="org.wso2.carbon.apimgt.impl.executors.APIExecutor">
                            </execution>
                            <execution forEvent="Deprecate"
                                       class="org.wso2.carbon.apimgt.impl.executors.APIExecutor">
                            </execution>
                        </data>
                    </datamodel>
                    <transition event="Deprecate" target="Deprecated"/>
                    <transition event="Re-Publish" target="Published"/>
                </state>

                  <state id="Deprecated">
                      <datamodel>
                          <data name="transitionExecution">
                              <execution forEvent="Retire"
                                         class="org.wso2.carbon.apimgt.impl.executors.APIExecutor">
                              </execution>
                          </data>
                      </datamodel>
                      <transition event="Retire" target="Retired"/>
                  </state>
  
                  <state id="Retired">
                  </state>
            </scxml>
        </lifecycle>
    </configuration>
</aspect>

• As we have done previously, we need to modify the Deprecated state block and the Retired state block by adding transitions.

<state id="Deprecated">
    <datamodel>
        <data name="transitionExecution">
            <execution forEvent="Retire"
                class="org.wso2.carbon.apimgt.impl.executors.APIExecutor">
            </execution>
            <execution forEvent="Re-Publish"
                class="org.wso2.carbon.apimgt.impl.executors.APIExecutor">
            </execution>
        </data> 
    </datamodel>
    <transition event="Retire" target="Retired"/>
    <transition event="Re-Publish" target="Published"/>
</state>

<state id="Retired">
    <datamodel>
        <data name="transitionExecution">
            <execution forEvent="Re-Publish"
                class="org.wso2.carbon.apimgt.impl.executors.APIExecutor">
            </execution>
        </data> 
    </datamodel>
    <transition event="Re-Publish" target="Published"/>
</state>

• Save the content and go again to the publisher portal.
• Select a retired API.
• Select the Lifecycle tab and now you can see the RE-PUBLISH button in there as below image.

RETIRED the API — WSO2 API Manager

• Once you click on that, the API will move to the PUBLISHED state as below.

Re-publish the API — WSO2 API Manager

• Since we have added the Re-Publish option to the DEPRECATED state, we can see the RE-PUBLISH button as the below image if the API is in the DEPRECATED state.

DEPRECATED the API — WSO2 API Manager

• Once we click on the RE-PUBLISH button, the API will move to the PUBLISHED state again as below.

Re-publish the API — WSO2 API Manager

For more information regarding the API Lifecycle customizations on APIM 3.0.0 version to 4.2.0 version, please refer to the documentation [4].

SO YEAH!!!, THE SOLUTION IS WORKING AS EXPECTED 😎😎😎

Congratulations!!! Now you have successfully configured a way to recover the deprecated/retired API. 🤠🤠🤠

Happy Recovering!!! 😎😎😎

[1] https://wso2.com/api-manager/#

[2] https://updates.docs.wso2.com/en/latest/

[3] https://apim.docs.wso2.com/en/4.2.0/design/lifecycle-management/customize-api-life-cycle/

[4] https://apim.docs.wso2.com/en/3.0.0/learn/design-api/lifecycle-management/customize-api-life-cycle/