8.1. Staging Concept

Normally customers do have multiple stages or environments, which may have different requirements in terms of security, versioning, etc. and it's obvious, that the program must support it.
As the Swagger-Definition & API-Config becomes the single source of truth, it must be the truth for all stages/environments and some environments need different settings. For instance stronger security rules in Production vs. Pre-Production or other Custom-Policies in the Cloud vs. On-Premise.

Apply staging

The tool is using overrides to apply different settings per stage to avoid, that the API-Developer needs to maintain multiple files with almost the same content. The idea is just to provide the "Delta" API-Config for the stage.
By using the option -s (stage) and the stage-id you inject the stage config. An example would be:

apim api import -s prod -a samples/petstore.json -c samples/minimal-config.json -h localhost -u apiadmin -p changeme

With that, the program is looking for an Production-API-Config override-file placed side by side to the main API-Config. That means you need to have the following files in your directory:

petstore.json                 # The API-Swagger-Definition  
minimal-config.json           # The Main-API-Config file with default settings  
minimal-config.prod.json      # The Config-File with settings for the prod environment  

Stage-Config

As described, the staging parameter (-s prod) will automatically infer what the corresponding config file is called (e.g. api-config.prod.json).
If you need more control over which staging configuration file to use, then you can also specify it manually through the -stageConfig parameter introduced in version 1.3.11. If you use both parameters at the same time, then -stageConfig is used to load the config file and -s prod only to load the conf/env.prod.properties. You can use this parameter for all import actions, such a APIs, Organizations, etc.

Here is an example:

apim api import -s api-env -c samples/basic/minimal-config-api-definition.json -stageConfig stageConfig/staged-minimal.json

The given stage config must be either absolute or relative to the primary configuration file. If the given stage config is not found a warning message is logged, but the process continues.
Such a stage config file (e.g. minimal-config-api-definition.prod.json) is merged with the main config-file and therefore only contain the required changes.

Environment settings

Additionally, also environment-specific parameters (such as the host, the users, handling of client apps, etc.) might be different from stage to stage. For instance, it might be desired to ignore Client-App-Handling in the production stage, but have it enabled for easier tests in all Pre-Production stages. Also, this is supported by providing so called: Environment-Properties.
Learn more on this page how this works

What is NOT possible / Limitations

You can basically override in your stage-file everything you can define in the main-contract.

But, "Deep"-Merge is unfortunately not supported. Let's assume the following main-config:

{
   "name":"Any API-Name",
   "path":"/my/path/to/api",
   "state":"published",
   "version":"1.0.0",
   "organization":"API Development",
   "securityProfiles":[
      {
         "name":"_default",
         "isDefault":true,
         "devices":[
            {
               "name":"API Key",
               "type":"apiKey",
               "order":0,
               "properties":{
                  "apiKeyFieldName":"KeyId",
                  "takeFrom":"HEADER",
                  "removeCredentialsOnSuccess":"false"
               }
            }
         ]
      }
   ]
}

And you would like to change the API-Key field: takeFrom to QUERY instead of HEADER for the Security-Profile. For that requirement, let's assume you have created an API-Config-File: minimal-config.prod.json like this:

{
   "securityProfiles":[
      {
         "devices":[
            {
               "name":"API Key",
               "type":"apiKey",
               "order":0,
               "properties":{
                  "takeFrom":"QUERY"
               }
            }
         ]
      }
   ]
}

That config will lead to an error, as the security profile in the stage-config is read on it's own and therefore incomplete. You need to add the complete profile-information. This limitation applies for all profiles, such a Outbound-, CORS, etc.

Perhaps in a later version deep-merge support will be added.