Merge Multiple API Definitions

Combine several API definitions, in the same or different formats, into one API with MergeConfiguration in the APIMatic Metadata file.

If your API is described in several definitions, APIMatic can merge them into one. The definitions can be in different formats, for example one OpenAPI and one RAML file. Merging is set up in MergeConfiguration in the APIMatic Metadata file.

Merging is different from splitting one definition across several files. APIMatic follows references across files on its own; you don't need to merge them.

How merging works

APIMatic merges two definitions at a time, in the order you set: the first with the second, then that result with the third, and so on. When the two disagree, the first one (the "left" one) wins by default.

Each definition is validated, and so is the merged result. Errors stop the merge. Warnings don't, but they can affect the result.

Set up the folders

Put each definition in its own subfolder of spec. A definition can span several files.
Add a metadata file to spec itself, next to the subfolders, with MergeConfiguration.
Optionally, add a metadata file to a subfolder for that definition's own import settings.

src/
  spec/
    APIMATIC-META.json      # MergeConfiguration
    payments/
      openapi.json
      APIMATIC-META.json    # optional: import settings for this API
    payouts/
      main.raml
      schemas/

A subfolder can hold further subfolders to merge; give it its own metadata file with MergeConfiguration.

src/spec/APIMATIC-META.json

{
  "MergeConfiguration": {
    "MergeApis": true,
    "MergeOrderOfDirectories": ["payments", "payouts"],
    "MergedApiName": "Acme API",
    "MergeSettings": {
      "ConflictStrategy": "KeepLeft"
    }
  },
  "ImportSettings": {
    "PreferJsonSchemaNameOverTitle": true
  }
}

Import settings in the top metadata file apply to every definition. A subfolder's own metadata file overrides them for that definition.

MergeConfiguration

Key	Type	Description
`MergeApis`	boolean	Required. Turns merging on. Default `false`.
`MergeOrderOfDirectories`	array of strings	Subfolders to merge, relative to the metadata file, in order. Changing the order changes the result.
`MergedApiName`	string	Name of the merged API.
`MergeSettings`	object	How conflicts are resolved. See below.

MergeSettings

Key	Type	Default	Description
`ConflictStrategy`	string	`KeepLeft`	How conflicts are resolved. See Conflict strategies.
`DescriptionConflictStrategy`	string	Same as `ConflictStrategy`	Strategy for conflicting descriptions only.
`DeepCompareFieldTypes`	boolean	`false`	Compares field types in depth when deciding whether two models are the same.
`AppendParentNameInNamingConflict`	boolean	`false`	Resolves name clashes by adding the parent's name instead of a number.
`NumberStartIndexForNameConflict`	number	`1`	First number added to clashing names.
`MergeMultipleAuthentication`	boolean	`true`	Keeps the authentication schemes of every definition.
`PrefixEntityNamesWithApiNameBeforeMerge`	boolean	`false`	Adds each API's name before its entity names, to avoid clashes.
`PostfixEntityNamesWithApiNameBeforeMerge`	boolean	`false`	Adds each API's name after its entity names, to avoid clashes.
`DeduplicateModels`	boolean	`true`	Removes or renames duplicate models. Names are compared without case, so `status` and `Status` clash. Turn it off only if model names are unique across your APIs.
`CompareModelsAndFieldsExamples`	boolean	`false`	Also compares examples when matching models and fields. This can be slow.
`SkipCodeGenValidation`	boolean	`false`	Skips the checks needed for SDKs and portals. Use it only when you just transform the merged definition.

Conflict strategies

Value	What happens
`KeepLeft`	Keeps the first definition's value and drops or adjusts the second's.
`KeepRight`	Keeps the second definition's value and drops or adjusts the first's.
`KeepBoth`	Keeps both values as they are. Falls back to `KeepLeft` where that isn't possible.
`Merge`	Combines the two values, changing them if needed. Falls back to `KeepLeft` where that isn't possible.

Merge Multiple API Definitions

How merging worksCopy Anchor Link

Set up the foldersCopy Anchor Link

MergeConfigurationCopy Anchor Link

MergeSettingsCopy Anchor Link

Conflict strategiesCopy Anchor Link

On this page

How merging works

Set up the folders

MergeConfiguration

MergeSettings

Conflict strategies