2.1.2 API Configuration file
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:
| 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
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.
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:
- Stage-Environment-File
- Generic Environment-File
- Operating-System environment variables
Important to know: If a variable can't be looked up, the variable declaration stay unchanged in the config-file.
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:787and basepath to:/api/v1/greatapi
The Port is optional.
SOAP-Service WSDL endpoints are not adjusted by this parameter.
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"
]
}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.
Use the API-Description as given in the API-Specification:
"descriptionType": "original"Manual can be used to override the documentation with your own markdown description:
"descriptionType": "manual",
"descriptionManual": "My markdown description"The given URL will be shown the API-Catalog:
"descriptionType": "url",
"descriptionUrl": "https://point.to.documentation-page.html"Is referencing a markdown file stored on the API-Manager instance:
"descriptionType": "markdown",
"descriptionMarkdown": "${env.DOCS}/myMarkdownFile.md"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.
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
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
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.
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.
---
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