Skip to main content

Transforming API Specifications

Depending on your environment, APIMatic offers the following ways to transform API definition files to a format of your choice if you have an API definition in one of the supported formats:

Transformer Configuration Settings​

You can even customize your transformation by adding metadata and additional settings provided by APIMatic. For more detail on these settings, learn how to Configure Transformer to improve your output.

Transform API via Web​

  1. On the APIMatic Dashboard, click on Transform API.

    APIMatic Transformer Dashboard

  2. You can either Upload the API Specification file (or .zip file for API merging) from your local system, or Specify the URL that points to the API specification file. In case of URLs, make sure that the URL must be a publicly accessible link - i.e. no localhost links or links hidden behind authentication. Select the desired Export Format from the dropdown menu and click on Convert.

    APIMatic Transformer Options

  3. APIMatic automatically performs validation on your specified file. The validation involves checks to ensure that the API definition is structurally correct and contains complete information to ensure comprehensiveness. There are 3 levels of validation messages that you may encounter:

    • Errors: Any syntax/semantic issues found in the API definition; for example, if a reference ($ref) in a JSON/YAML file has an invalid path that cannot be resolved, API transformation cannot proceed in case of an error. You will be required to fix the issues listed for your definition if that happens.
    • Warnings: Any unexpected behavior that may affect the output; for example, if the parameter example provided is invalid. Warnings will not halt API transformation, but it is recommended that you fix these issues so your API definition results in the best possible experience.
    • Messages: Recommendations or suggestions that can help enhance your API definition and its completeness. For example, messages can point out that an endpoint description or a parameter example is missing. Messages will not halt API transformation.

    Once the validation errors are resolved (if any), click Proceed to move to the next step.

    APIMatic Transformer Validation

  4. Once transformation is successful, the transformed file is automatically downloaded to your default download location with naming convention <FileName>-<ExportFormatName>. If it does not download, you may click on the download link provided. If your subscription plan allows, you can also proceed to generate an interactive developer experience portal for your API or view portals of our customers. Otherwise, click Close.

    APIMatic Transformer Successful

Transform API Definition via API​

You can use APIMatic's API in any supported language to build API Transformer into your CI/CD pipeline to automatically execute transformations every time changes are pushed. The transformed file is stored on the server for future accessibility. You can transform through a file on the system or uploaded on the server. You can also perform various functions like deleting a transformation, downloading the input file and getting logs for existing transformations.

You can perform the following actions through the Transformer API endpoints:

Transform API via APIMatic CLI​

APIMatic CLI allows you to transform an API definition in supported API specification formats through the terminal. To get a detailed insight, refer to our Transform API via CLI Docs.