-
Notifications
You must be signed in to change notification settings - Fork 19
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-Formatted file which contains the required settings for the API-Manager. This is a very 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 a 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 or markdown |
| descriptionUrl | When type: url, points to the URL containing the API-Description |
| descriptionMarkdown | When type: markdown, must start with a ${env.PROPERTY} resolving to a location on HDD |
| securityProfiles | Control the Inbound-Security settings of your API. Learn more |
| outboundProfiles | Control how the API-Manager should authenticate to the API-Service-Provider and make use of Custom-Policies. 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 API-Import Swagger-Promote 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 Swagger-Promote after removing some potential duplicates.
In certain situations it might be useful to use variables in your API-Configuration, which is possible since version 1.5.4.
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 Swagger-Promote to dynamically change or add the required host and also change basepath parameter in your API-Specification before inserting it into API-Manager.
Additionally, since version 1.6.2, the backendBasepath is used to update the schemes in the Swagger-Definition.
"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.
If you don't want to change the Swagger-File itself and instead configure the API-Proxy with the desired backendBasePath only, disable it with: replaceHostInSwagger=false.
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 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"
}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.
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.