Skip to main content

Transforming Your API Specification

If you have an API specification file in one of the supported input formats, you can transform it instantly into one of the supported output formats. Various options are available to help you configure the transformation process which are described in detail here.

note

You need to be signed in from an APIMatic account to follow this tutorial. Signing up is free.

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

  1. Here you can upload your API specification document by selecting a file from your local machine using the Choose file option or by specifying a public URL that points to the API specification file. Click on Convert.

    note

    ZIP files are supported in case you want to transform a single API specification split into multiple files. Conversely, if you want to transform multiple API specifications into a single API specification document of any format, you will first need to merge the API specifications together before transforming them to the desired format.

    Transform via File or URL

  2. The conversion process first performs a syntax and semantic validation of the input API specification format. If any errors, warnings or informational messages are found at this point, they are displayed in the validation summary dialog box and may need to be fixed before you can transform your file again. Apart from validation, messages containing additional information is also displayed e.g. auto-identified format of the input specification document and number of models and endpoints found in the document, etc.

    note

    For FAQs and troubleshooting tips related to API Transformer, please visit our related documentation here.

    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, 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 behaviour 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.

    Validation

    If there are no errors, you can click on Proceed and your transformed file should start downloading.