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.
For detail on the API merging settings, refer to API Merging Settings.
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.
APIMATIC-META.jsonmetadata file (containing the API Merging settings) at the root of this parent directory. Check out this sample directory structure with two API definitions:
APIMATIC-META.json // Will contain merge settings
APIMATIC-META.json // Can contain any specific settings for CodeGen, import/export etc
- An example of what the Merge settings may look like in the
APIMatic-META.jsonplaced at the root is shown in this snippet:
"MergeOrderOfDirectories": ["spec1", "spec2"],
"MergedApiName": "Merged API",
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
You can merge APIs during API import or during API transformation.
On the APIMatic Dashboard, click on the Import option.
Click on Browse and select the
.zipfile containing the API definitions to merge. Click on Import.
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: