Skip to main content

Merge Multiple API Definitions

You can import multiple API definition files and merge them to create a unified API Portal and SDK for each language. By default, APIMatic merges APIs using the Take Left merge strategy. When two API definition files are being merged, APIMatic will try to keep elements such as endpoints and schemas from both the APIs. If there is a conflict, the value from the first API will take precedence.

note

For detail on the API merging settings, refer to API Merging Settings.

Directory Structure​

  • In a directory, put each API definition (whether it is a single file or composed of multiple files) into individual sub-directories. These sub-directories can also contain the metadata file specific to the API definition for any additional configurations like CodeGen settings.

  • Place the APIMATIC-META.json metadata file (containing the API Merging settings) at the root of this parent directory. Check out this sample directory structure with two API definitions:

dir\
    APIMATIC-META.json // Will contain merge settings
    spec1\
        openapi.json
        APIMATIC-META.json // Can contain any specific settings for CodeGen, import/export etc
    spec2\
        openapi.json
        APIMATIC-META.json
  • An example of what the Merge settings may look like in the APIMatic-META.json placed at the root is shown in this snippet:
...
{
    "MergeConfiguration": {
        "MergeApis": true,
        "MergeOrderOfDirectories": ["spec1", "spec2"],
        "MergedApiName": "Merged API",
        "MergeSettings": {
            "ConflictStrategy": "KeepLeft"
        }
    }
}
...
important

The order of the API definition files in the MergeOrderOfDirectories setting matters, as the merging will be applied based on this order.

  • Zip this directory, with the metadata and API definition sub-directories as API import will expect a .zip file.

API Merging​

note

You can merge APIs during API import or during API transformation.

  • On the APIMatic Dashboard, click on the Import option.

    Import API

  • Click on Browse and select the .zip file containing the API definitions to merge. Click on Import.

    Merge APIs

  • Before import, APIMatic performs validation of your API definition files. The validation involves checks to ensure that the API definitions are structurally correct and contain complete information to ensure comprehensiveness of the files. 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 GET method contains a request body. API definition file import 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 import, 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 import.

  • Once the API definition is imported, it will be visible in the list of APIs in the Dashboard as shown below:

    Added Merged API

  • You can now create an API portal or generate SDKs for this merged API.