Refactoring REST APIs

1. Switch to Projects.

2. Do any of the following:

   • Right-click your web service in the Navigator panel and select Refactor Definition from the context menu:

     

     Click the image to enlarge it.

   – or –

   • Select your web service in the Navigator panel and click Refactor on the toolbar:

     

     Click the image to enlarge it.

   – or –

   • Select your web service in the Navigator panel and choose API > Refactor Definition from the main menu:

     

     Click the image to enlarge it.

The Refactor Definition dialog will appear.

Use the Refactor Definition dialog to select the update definition to be used during refactoring. The OpenAPI, Swagger, and WADL formats are allowed:

Click the image to enlarge it.

1. Enter the definition:

   In the Definition URL field, you can either:

   • Manually enter the URL.

   • Click Choose to open the Choose API Definition dialog, which offers three tabs for selecting the API definition source:

     • My Computer: Select a file from your computer. Additionally, choose the protocol from the Protocol dropdown.

       

       Click the image to enlarge it.

     • URL: Manually enter a URL in the Source field.

       

       Click the image to enlarge it.

     • SwaggerHub: Import an API definition from SwaggerHub. This option is available if you've integrated ReadyAPI with your SwaggerHub account. For more details on integration, see the SwaggerHub integration page.

       Select one of the following options:

       • My API: Search for and select an API from your private SwaggerHub account.
       • Public API: Search for and select an API from publicly available APIs on SwaggerHub.
       

       Click the image to enlarge it.

       Tip:	Use the Filters button to refine the API list: Select specific API specifications: OAS2, OAS3, OAS3.1, AsyncAPI, or All. Optionally, select Private or Public for My API. Click Select All or Deselect All to manage your filter selections.

     After making your selection, click Select. The system will then display the Refactor Definition dialog with your chosen definition.

2. Refactor Definition Settings:

   • In the Refactor Definition dialog:

     • Select the Create new requests checkbox to generate new requests for any new methods.

       Note:

       If the definition file includes multiple services, choose the relevant service. Click the image to enlarge it.

3. Finalize:

   • Click OK to confirm and load the updated API definition.

     ReadyAPI will load and analyze the new definition. In the subsequent dialog, set a correspondence between old and new operations.

In the Refactoring REST Definitions dialog, specify which existing resources, methods and requests match new ones:

Click the image to enlarge it.

The dialog displays old items (resources, methods or requests) on the left and new items on the right. ReadyAPI automatically matches the old items with the new ones. The old items that do not match the new ones appear in red, while the new items that do not match the existing ones appear in blue.

Match existing resources, methods and requests with new ones in the following way:

• To indicate that an existing resource, method or request matches a new one, you connect them. To do that, select an item in one panel, then select the matching item in the opposite panel and click Connect:

  

  Click the image to enlarge it.

• If the connected resource, method or request does not match the new one, disconnect them. To do that, select an item in one of the panels (ReadyAPI will select the connected item in the opposite panel automatically) and click Disconnect:

  

  Click the image to enlarge it.

When you click Next, ReadyAPI will do the following:

• If some existing resource, or its method, or a request matches the new resource, method or request (that is, if the dialog shows a thin grey line between them automatically, or if you’ve connected them manually in the dialog), then ReadyAPI will update existing items with the new item data. At that, existing child methods and requests that don’t have new matching items will not be changed. Also, ReadyAPI will add new methods and requests to the existing resource.

• If neither existing resource, nor its methods and requests match any new resource, method or request, the existing item(s) are deleted.

• If a new resource and its methods and requests don’t match any existing item, ReadyAPI will add these new items to the service definition stored in your project.

After you match all the needed items, click Next.

ReadyAPI displays the Refactoring REST Definitions dialog:

Click the image to enlarge it.

The dialog shows the differences between the current and new versions of the linked items. Review the suggested changes and adjust the final variant, if needed.

For linked methods, specify how ReadyAPI should treat representations. Select Overwrite to replace representations with the updated versions, or select Ignore to keep the current representations.

If a parameter is absent in the new definition, select what ReadyAPI should do: remove the parameter or link it with one of the new parameters. In the latter case, ReadyAPI will replace the absent parameter with the linked one. In order not to lose the current value of the parameter, make sure to select the Keep existing value option in the subsequent Parameters Refactoring dialog.