Publish an API Proxy

Publish API Proxy with OpenAPI Spec

Note:
API Connectivity Manager supports the OpenAPI Specification version 3.0 and 3.1. If your spec uses the 2.0 standard, you must convert it before uploading it.

Uploading an OAS Schema

OAS Schemas can be uploaded to API Connectivity Manager and stored for use as references for Proxy deployments. The routes contained in the OAS Schema will be used to create the routes for your Proxy

Creating a Proxy with an OAS

After you have uploaded your OAS Schema as an API Doc, you can then reference that API Doc in your Proxy deployments using the specRef parameter in the JSON payload. Using the specRef will then associate that OAS Schema in API Connectivity Manager and allow API Connectivity Manager to create your routes from the information contained in the OAS Schema.

Extended support for OAS in API Connectivity Manager

API Connectivity Manager now allows you to set up an API gateway using Open API Specification by supporting the creation of Backends (upstream servers) from the supplied OAS using an API Connectivity Manager specific x- extension in your OAS document. API Connectivity Manager now also supports server URL templating in the global URL(s).

"servers": [  
  {  
    "url": "https://{server}.example.com/api/{version}",  
    "variables": {  
      "version": {  
        "default": "v1"  
      },  
      "server": {  
        "default": "staging"  
      }  
    },  
    "x-acm-append-rule": "NONE",  
    "x-acm-strip-basepath": false,  
    "x-acm-backends": [  
      {  
        "serviceName": "pets-backend",  
        "serviceVersion": "pets-backend-v1",  
        "serviceLabel": "default",  
        "contextRoot": "/dev",  
        "upstreams": [  
          {  
            "url": "https://gecho1.null.ie",  
            "maxFails": 10,  
            "maxConnections": 5,  
            "failTimeout": "5s",  
            "slowStart": "10s"  
          },  
          {  
            "url": "https://gecho2.null.ie",  
            "maxFails": 5,  
            "maxConnections": 8,  
            "failTimeout": "15s",  
            "slowStart": "3s"  
          },  
          {  
            "url": "https://gecho3.null.ie",  
            "maxFails": 7,  
            "maxConnections": 33,  
            "failTimeout": "35s",  
            "slowStart": "1s"  
          }  
        ]  
      }  
    ]  
  }  
],

Server URL Templating

"servers": [  
  {  
    "url": "https://{server}.example.com/api/{version}",  
    "variables": {  
      "version": {  
        "default": "v1"  
      },  
      "server": {  
        "default": "staging"  
      }  
    },  

In the above section, we can see how server URL templating will make substitutions with a matching value from the variables section of the server object in the specification. Each placeholder in the URL must have a matching variable in the variables section or the validation will fail and return an error.

Creating Backends

This section explains how to create a backend target for our API Gateway configuration, a Backend is a collection of upstream servers bundled under one “Service label”. An API Gateway can have multiple Backends which can each contain multiple upstream servers.

"x-acm-backends": [  
      {  
        "serviceName": "pets-backend",  
        "serviceVersion": "pets-backend-v1",  
        "serviceLabel": "default",  
        "contextRoot": "/dev",  
        "upstreams": [  
          {  
            "url": "https://server.example.com",  
            "maxFails": 10,  
            "maxConnections": 5,  
            "failTimeout": "5s",  
            "slowStart": "10s"  
          },

In the above example, we can see how to create a single Backend with a single upstream server.

All values supplied in the OAS Specification are only modifiable through the OAS Specification and not through the API or UI, this means that the OAS Specification is the source of truth for all values supplied within it. If values are omitted from the OAS Schema then they may be added or modified via the API or UI.

Proxy Basepath

It is possible to modify the basepath provided using two additional extensions: x-acm-append-rule and x-acm-strip-basepath.

x-acm-append-rule is a legacy configuration option that was used to either prepend or append the version field from the info section to your API basepath, going forward the basepath should be added explicitly to the global server URL section in exactly the manner in which it is to be used, for example: https://myserver.host.com/api/v1

x-acm-append-rule defaults to NONE and the version field in the info section is only used as the document version metadata in favor of explicitly adding the version to the server URL. x-acm-append-rule should ONLY be used for legacy deployments that used a value other than NONE

x-acm-strip-basepath is a boolean value that denotes whether to strip the basepath from the request URI before proxying the request to the backend servers.

• When you upload an OpenAPI spec, API Connectivity Manager automatically generates a name for the API Docs object using the following format:

"info.title"-"info.version"

• The string is “URL-ized”, meaning any whitespace gets converted to dashes (-) and all letters are lowercase. If we used the OpenAPI example Petstore API, the auto-generated name for the API Docs would be petstore-v1.

• UI
• API

Publish an API Doc to Developer Portal

Next, you can publish API Docs to your Developer Portal.

API Connectivity Manager uses the portalConfig.hostname setting to connect your Dev Portal Proxy to the Developer Portal. You should define this field using the hostname that you assigned to the Developer Portal in the Set Up a Developer Portal guide.

• UI
• API

{
    "name": "{{proxyName}}",
    "specRef": "petstore-1",
    "version": "v1",
    "proxyConfig": {
        "hostname": "{{environmentHostname}}",
        "ingress": {
            "basePath": "/v1"
        },
        "backends": [
            {
                "serviceName": "petstore-api-svc",
                "serviceTargets": [
                    {
                        "hostname": "petstore.example.com"
                    }
                ]
            }
        ]
    },
    "portalConfig": {
        "hostname": "{{portalClusterHostname}}"
    }
}