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 Sep 26, 2019 · 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 can contains only the needed settings for the API-Manager. This is the most minimal supported version:

{
    "name": "Minimal API",
    "path": "/minimal/api/v1",
    "state": "unpublished",
    "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": "https://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-General basic settings

name - Just the name of the API. Can be changed at any time
path - 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
state - Defines the state of the API. Supported: unpublished, published, deprecated, retired & deleted. Just declare the state you want for your API and the tool is doing the rest for you.
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.
apiRoutingKey - 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.
descriptionType - What kind of description to be used: original, manual, url or markdown
descriptionManual - When type: manual, the provided API Markdown description
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
vhost - The V-Host this API should be exposed when Published (works only on a published API)
backendBasepath - Changes the downstream server. (Learn more)

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

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

Inbound Security settings

Inbound Security controls how a consuming application must authenticate themselves against the exposed API. The API-Manager support by default: API-Key, OAuth, OAuth (External), AWS-Signing, HTTP-Basic, Passthrough, Custom-Policy

Please note: As of now only the Default Security-Device is supported. That means, you cannot combine multiple security devices and link it to the API.

Learn more about Inbound Security config here

API-Outbound Authentication

This controls how the API-Manager itself should authenticate themselves to the API-Service-Provider. The following is supported today: API-Key, HTTP-Basic, HTTP Digest, Custom-Policy, OAuth & SSL.

Please note: As of now only the Default Authentication-Device is supported. That means, you cannot combine multiple Authentictation devices and link it to the API.

Learn more about API-Outbound Security config here

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.

Quota setup

Please refer to Configute API-Quotas

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

Clone this wiki locally