Refactoring REST APIs

Applies to ReadyAPI 3.56, last modified on November 25, 2024

If your web service is updated, you may need to change test cases and requests in ReadyAPI. ReadyAPI offers the Refactor Definition command that simplifies this task. The command invokes a dialog box. Use it to set a correspondence between existing and new resources, methods and requests, as well as their parameters. Then, ReadyAPI will automatically update the requests and test steps in your project so that they match the updated specification.

Note: If you do not have a WADL or Swagger/OpenAPI definition for your API (for example, if you created a project from an endpoint), you will not be able to perform REST refactoring.

To use refactoring, you need the ReadyAPI Test Pro license.

1. Start refactoring

  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:

      Clicking Refactor Definition

      Click the image to enlarge it.

    – or –

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

      ReadyAPI 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:

      Calling Refactor Definition from menu

      Click the image to enlarge it.

The Refactor Definition dialog will appear.

2. Load the updated definition

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

The Refactor Definition dialog

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.

        Selecting a file from my computer

        Click the image to enlarge it.

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

        Entering URL

        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.
        Importing API definition from 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.

        Multiple services

        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.

3. Refactor definition

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

REST Refactoring

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:

    REST refactoring: Connecting items

    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:

    REST refactoring: Disconnecting items

    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.

4. Refactor properties

ReadyAPI displays the Refactoring REST Definitions dialog:

ReadyAPI: Manual Refactoring

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.

See Also

Refactoring SOAP APIs
Documenting Interfaces
Rest Services

Highlight search results