2.1.2 API Configuration file - Axway-API-Management-Plus/apim-cli GitHub Wiki

The API-Configuration, together with the provided Swagger- or WSDL-File creates the complete API-Definition needed by the API-Manager registry.
The API-Configuration file basically contains everything for what the API-Definition (Swagger/WSDL) itself isn't made for, like Custom-Properties to use, which Custom-Policies, etc. that is used by the API-Manager at runtime.

You can either create that API-Configuration file manually yourself or you can export an existing APIs from the API-Manager to get it.

The API-Config is a JSON / YAML -Formatted file which contains the required settings for the API-Manager. This is a basic version:

{
    "name": "Minimal API",
    "path": "/minimal/api/v1",
    "state": "unpublished",
    "retirementDate": "01.09.2050",
    "summary": "The summary, which will appear in overview screens",
    "image": "../api/images/myGreatAPIImage.png",
    "version": "1.0.0",
    "apiDefinition": "samples/petstore.json",
    "organization": "API Development", 
    "apiRoutingKey": "V1", 
    "descriptionType": "markdown", 
    "descriptionMarkdown": "${//env.DOCUMENTS//}/api/docu.md", 
    "vhost": "myapi.specific-host.com", 
    "backendBasepath": "https://host.xyz.com:8665/api/v1", 
}

The example above will create a Backend-API + Frontend-API using default Passthrough-Security.

This can be extended about additional API-Configuration settings as explained on this page:

API-Configuration fields

Field	Comment
name	The name of the API. Can be changed at any time
path Key*	This is key information, as it's used to identify the existing actual API in API-Manager. When changed a new API is created
vhost Key*	The V-Host this API should be exposed when Published (until 7.6.2 SP3 was working on a published API only - newer versions of the API-Manager also support V-Host for Unpublished APIs)
apiRoutingKey Key*	Available in API-Manager 7.6.2 or higher - Allows to expose multiple version of the same API and routing is controlled by this parameter. See here for more details.
backendBasepath	Changes the downstream server. (Learn more)
state	Defines the state of the API. Supported: unpublished, published, deprecated, retired & deleted. Declare the state you want for your API and the tool is doing the rest for you.
retirementDate	The date the API should be retired. Only used, when state is set to deprecated. Supported formats: dd.MM.yyyy, dd/MM/yyyy, yyyy-MM-dd, dd-MM-yyyy
summary	The API-Summary line
image	Provide the name of the image. The file must be stored either in the same directory as the Config-File, relative to it or using an absolute path.
version	It's just a meta information. Can be changed at any time and will be set even to an existing API found based on the path
apiDefinition	Optional, as an alternative to parameter -a define the Swagger/WSDL direclty in the configuration file
organization	The organization this API should belong to. The tool validates the organization exists and has a development flag. If the tool is started by an Org-Admin account this property is ignored.
descriptionType	What kind of description to be used: original, manual, url, markdown or markdownLocal. Learn more
descriptionUrl	When type: url, points to the URL containing the API-Description. Learn more
descriptionMarkdown	When type: markdown, must start with a ${env.PROPERTY} resolving to a location on HDD. Learn more
markdownLocal	When type: markdownLocal. Learn more
securityProfiles	Control the Inbound-Security settings of your API. Learn more
outboundProfiles	Control how the API-Manager should authenticate to the API-Service-Provider. Learn more
tags	Set tags to your API. Learn more
customProperties	Set Custom-Properties for your API. Learn more
corsProfiles	Configure CORS. Learn more
caCerts	Configure Inbound- and Outbound Certificates. Learn more
applicationQuota	Configure the Application Default-Quota. Learn more
systemQuota	Configure the Application Default-Quota. Learn more
applications	Automatically create Application-Subscriptions. Learn more
clientOrganizations	Automatically grant access to configured Organizations. Learn more

It is highly recommended to review the Example-Configuration files stored in samples folder for further reference.

Table of contents

How the Actual API is looked up
Understand how the Actual API is lookup.

Using variables in your config file
Use variables in your API-Configuration file to make it more flexible for staging.

Change the backend
Change the backend defined in your API-Definition when importing your API.

Tag your API
Manage tags

Custom properties
How to make use of API custom properties.

Custom policies
Explains how to deal with API Custom-Policies

Setup certificates
How API certificates are handled by the CLI

CORS profiles
Setup CORS for your API

How the Actual-API is looked up?

The CLI works on the Desired- and Actual-API. The Desired-API is what you have declared in the API-Config-File & Swagger/WSDL, while the Actual-API is the one which is currently managed by API-Manager, which could be even an Non-Existing API.
In order to load/identify the actual API, which must be compared with the desired API, the following keys/criteria are used to lookup the API: Path, V-Host & API-Routing-Key. They are used in combination to identify an actual API, which must be unique.
For example, when configuring two APIs having the same API-Path, they only become unique with different V-Hosts or a API-Version-Routing-Key. Therefore the given Desired-API must provide the right keys to make the Actual-API unique.
The following two API configuration are valid as the V-Host is different:

{
  "name" : "My API 1",
  "path" : "/api/v1/weather",
  "state" : "published",
  "vhost" : "abc.customer.com",

{
  "name" : "My API 2",
  "path" : "/api/v1/weather",
  "state" : "published",
  "vhost" : "xyz.customer.com",

Also, these configs are valid, when using the API-Version-Key routing feature of the API-Manager (Enable query string version routing):

{
  "name" : "My API 1",
  "path" : "/api/v1/weather",
  "state" : "published",
  "apiRoutingKey" : "1.0.0",

{
  "name" : "My API 2",
  "path" : "/api/v1/weather",
  "state" : "published",
  "apiRoutingKey" : "1.0.1",

Obviously it is also possible to provide all keys in combination:

{
  "name" : "My API 2",
  "path" : "/api/v1/weather",
  "state" : "published",
  "vhost" : "xyz.customer.com",
  "apiRoutingKey" : "1.0.1",

Please note:
During replication with apim api import it is validated, that the Actual-API based on the given keys is unique and if not an error is reported:
No unique API found
In that case, please validate in the API-Manager UI, that the API is really unique and re-run the CLI after removing some potential duplicates.

Using variables in API-Config file

In certain situations it might be useful to use variables in your API-Configuration, which is possible using the CLI.
With that you can for instance configure the following:

"implicitGrantLoginEndpointUrl":"${oauthEndpoint}/api/oauth/authorize",

instead of the having the OAuth-Endpoint manually configured. Another great example is to externalize required passwords, credentials into variables:

         "parameters":{
            "source":"file",
            "certFile":"../certificates/clientcert.pfx",
            "password":"${myKeytorePassword}",
            "trustAll":true
         }

The variables you declare are looked up in the following sequence and the first match is used:

1. Stage-Environment-File
2. Generic Environment-File
3. Operating-System environment variables

Important to know: If a variable can't be looked up, the variable declaration stay unchanged in the config-file.

Parameter backendBasepath

Quite often the Swagger-/OpenAPI-Definition contains an inappropriate backend host. For instance, a host from the development-environment, which doesn't work in production environments. Also, it's important to change the host information when staging the API from QA --> PRE-PROD --> PROD.
Using the optional API-Config-File parameter: backendBasepath you can instruct the APIM-CLI to dynamically change or add the required host. It will edit basepath in frontend API.

Also, in some cases we need to override basepath parameter in your API-Specification before inserting it into the API-Manager. In that case use the parameter overrideSpecBasePath=true Additionally, the backendBasepath is used to update the schemes in the API-Specification.

  "schemes": [
    "https",
    "http"
  ]

These schemes are completely replaced by the protocol given in the backendBasepath.

The parameter can have one of the following formats:

• "backendBasepath":"https://prod.api.server.com:787"
  This changes the host in your Swagger-File to: prod.api.server.com:787
  If you attach as base path to it:
• "backendBasepath":"https://prod.api.server.com:787/api/v1/greatapi"
  This changes the host in your Swagger-File to: prod.api.server.com:787 and basepath to: /api/v1/greatapi

The Port is optional.

SOAP-Service WSDL endpoints are not adjusted by this parameter.

Tags

The tags are provided at the root level of the API-Definition.

"tags":{
   "tag-name 2":[
      "value 3",
      "value 4"
   ],
   "tag-name 1":[
      "value 1",
      "value 2"
   ]
}

API-Description

The API Manager offers several ways to configure the description of an API that should appear in the catalog. These are of course also supported by the APIM CLI and beyond that there are other interesting possibilities.

Original

Use the API-Description as given in the API-Specification:

"descriptionType": "original"

Manual

Manual can be used to override the documentation with your own markdown description:

"descriptionType": "manual",
"descriptionManual": "My markdown description"

Url

The given URL will be shown the API-Catalog:

"descriptionType": "url",
"descriptionUrl": "https://point.to.documentation-page.html"

Markdown

Is referencing a markdown file stored on the API-Manager instance:

"descriptionType": "markdown",
"descriptionMarkdown": "${env.DOCS}/myMarkdownFile.md"

MarkdownLocal

And finally an option which is only available via the APIM CLI. You can reference a number of Markdown files and also mix them with the original API description:

"descriptionType": "markdownLocal",
"markdownLocal": [
  "../myMarkdown1.md", "ORIGINAL", "myMarkdown2.md"
]

This configuration creates a description that references the two Markdown files and uses the original API description in the middle.

Files must point to a file containing the API-Description. Path must be relative to the config-file or absolute. Is merged by the CLI into the API-Description as manual description. Hence the export contains a manual description with the merged content.

Custom-Properties

The Custom-Properties are provided at the root level of the API-Definition. The program validates, that the provided custom properties are configured and valid the API-Manager.

"customProperties":{
   "customProperty1":"Test-Input 1",
   "customProperty2":"1",
   "customProperty3":"true"
}

Please note: The APIM-CLI is validating during import if the custom properties you have configured are valid or there are missing custom properties. You can get a list of all configured properties with the following command:

apim settings get -s demo -type customProperties

Custom-Policies

The Axway API-Manager supports to execute custom policies for every API and they are managed as part of the Outbound-Profile.
The following is an API, having no other configuration, but all possible custom policies configured. This gives you an understanding how easy it is to attach custom policies:

{
	"name": "Samples All Policies",
	"path": "/sample/allpolicies/api/v1",
	"state": "unpublished",
	"version": "1.0.0",
	"organization": "API Development",
	"outboundProfiles": {
		"_default": {
			"authenticationProfile": "_default",
			"requestPolicy": "Sample Request Policy 1",
			"responsePolicy": "Sample Response Policy 1",
			"routePolicy": "Sample Roputing Policy 1",
			"faultHandlerPolicy": "Sample Fault-Handler Policy 1"
		}
	}
}

Please note: The APIM-CLI is validating during import if the custom policies you have configured are valid. You can get a list of all configured policies with the following command:

apim settings get -s demo -type policies

Certificates Settings

To import certificates used for Inbound- and Outbound-Communication please add the following to your API-Config at the Root-Level:

"caCerts":[
   {
      "certFile":"/com/axway/apim/test/files/cacerts/swaggerio.crt",
      "useForOutbound":true,
      "useForInbound":false
   },
   {
      "certFile":"/com/axway/apim/test/files/cacerts/GoDaddyRootCertificateAuthority-G2.crt",
      "useForOutbound":true,
      "useForInbound":false
   },
   {
      "certFile":"/com/axway/apim/test/files/cacerts/GoDaddySecureCertificateAuthority-G2.crt",
      "useForOutbound":true,
      "useForInbound":false
   }
]

The provided certificate files will be automatically uploaded to the API-Manager. You can use relative and absolute paths in combination. Relative means: Relative to the given API-Configuration file!!
Important to note: By default the API-Manager automatically downloads all required Certificates from the Backend-Services. As long, as you don't need any custom certificate there is no need to add one here.
However, if you need to use at least one custom certificate, this will be considered as the "desired" state and therefore all certificates are overwritten by the one you defined. That means, you have to include all certificates, when using 1 Custom-Certificate.

CORS-Profile Settings

Please note: At the moment only a global CORS-Profile for all methods can be configured.

"corsProfiles":[
   {
      "name":"New CORS Profile",
      "isDefault":false,
      "origins":[
         "*"
      ],
      "allowedHeaders":[
         "Authorization"
      ],
      "exposedHeaders":[
         "via"
      ],
      "supportCredentials":false,
      "maxAgeSeconds":0
   }
]

isDefault - No need to change.

Yaml configuration file format.

---
name: petstore3
path: /api/v3
state: published
version: 1.0.17
organization: orga
apiSpecification:
  resource: /api_definition_1/petstore-openapi30.json
backendBasepath: https://petstore3.swagger.io/inboundProfiles:
  _default:
    monitorAPI: true
    queryStringPassThrough: false
    monitorSubject: authentication.subject.id
    securityProfile: _default
    corsProfile: _default
  createUser:
    monitorAPI: true
    queryStringPassThrough: false
outboundProfiles:
  _default:
    requestPolicy: Validate Size & Token
    responsePolicy: Remove Header & Audit data
    authenticationProfile: _default
  deletePet:
    routeType: proxy
    authenticationProfile: _default
securityProfiles:
  - name: _default
    isDefault: true
    devices:
      - name: API Key
        type: apiKey
        order: 1
        properties:
          apiKeyFieldName: KeyId
          takeFrom: HEADER
          removeCredentialsOnSuccess: true
caCerts:
  - certFile: swagger.io.crt
    inbound: false
    outbound: true
  - certFile: Amazon.crt
    inbound: false
    outbound: true
  - certFile: AmazonRootCA1.crt
    inbound: false
    outbound: true
  - certFile: StarfieldServicesRootCertificateAuthority-G2.crt
    inbound: false
    outbound: true
applicationQuota:
  restrictions:
    - method: "*"
      type: throttle
      config:
        period: second
        per: 2
        messages: 1000
systemQuota:
  restrictions:
    - method: "*"
      type: throttle
      config:
        period: second
        per: 2
        messages: 1000
clientOrganizations:
  - orga
applications:
  - name: Test App 2008
    enabled: true
    state: approved
    permissions: []
    appScopes: []
customProperties:
  customProperty1: public
  customProperty4: true