Skip to content
This repository has been archived by the owner on Aug 11, 2022. It is now read-only.

2. API Configuration

Jump to bottom
Chris Wiechmann edited this page Jan 21, 2020 · 20 revisions

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 the API-Definition (Swagger/WSDL) itself isn't made for, like Custom-Properties to use, or which Routing-Policy should be used by the API-Manager at runtime.

The API-Config is a JSON-Formatted file which contains the required settings for the API-Manager. This is the most minimal supported 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", 
}

It 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 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.

Another way to create the API-Configuration is by using the API-Manager to setup the API manually once and export it.

How the Actual-API is looked upped?

Swagger-Promote 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, a number of keys/criteria are used.
Until Swagger-Promote version 1.6.4 only the API-Path (/api/v1/weather) was used to lookup the Actual-API. In order to make the API-Lifecycle-Management easier, Swagger-Promote also supports the V-Host & API-Routing-Key as an additional keys. They are used in combination with the API-Path to identify an actual API.
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.

Using variables in API-Config file

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:

  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 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:

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.

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"
   ]
}

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"
}

Custom-Policies

The settings provided in the Outbound-Profiles reflects what can be done in the API-Manager FE-API Tab: Outbound. This includes which polices to use or what kind of authentication to be used for the downstream server.

"outboundProfiles":{
   "_default":{
      "requestPolicy":"Request policy 1",
      "routePolicy":"Routing policy 1",
      "responsePolicy":"Response policy 1",
      "faultHandlerPolicy":"Faulthandler policy 1"
   }
}

The program validates, that the Policies configured here are configured in API-Manager, if not an error is returned.

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.

☝️ Swagger-Promote has been discontinued and is replaced by the new APIM-CLI

Clone this wiki locally