Publish an API Gateway and Developer Portal

Learn how to use NGINX Management Suite API Connectivity Manager to publish an API Proxy with a Developer Portal.

Overview

In NGINX Management Suite API Connectivity Manager (ACM), Services represent your Backend APIs. Proxies represent the NGINX reverse proxy that routes traffic to your backend service and to the Developer Portal. This guide provides instructions and examples for publishing an API and a Developer Portal by using the REST API.

Before You Begin

You should complete the following Quick Start Guides before proceeding with the steps in this guide:

1. Set Up an API Gateway Environment
2. Set Up a Developer Portal Environment

Add a Services Workspace

First, create a Services Workspace. This is a team space where you can manage the API’s lifecycle.

{
    "name": "{{proxyWorkspaceName}}",
    "metadata": {
        "description": "Petstore Team Workspace"
    },
    "contactDetails": {
        "adminEmail": "admin@example.com",
        "adminName": "I.M. Admin",
        "adminPhone": "555 123 1234"
    }
}

Set Up an API Proxy

Next, add an API Proxy.

The API Proxy connects your backend API service to the API Gateway cluster using the proxyConfig.hostname setting. You should define this field using the hostname that you assigned to the API Gateway cluster in the Set Up an API Gateway guide.

API Proxy without OpenAPI Spec

The basic configuration below creates an API Proxy to a backend service.

{
    "name": "{{proxyName}}",
    "metadata": {
        "description": "Swagger Petstore Proxy"
    },
    "version": "v1",
    "proxyConfig": {
        "hostname": "{{environmentHostname}}",
        "ingress": {
            "basePath": "/v1",
        },
        "backends": [
            {
                "serviceName": "petstore-api-svc",
                "serviceTargets": [
                    {
                        "hostname": "petstore.example.com"
                    }
                ]
            }
        ]
    }
}

API Proxy with OpenAPI Spec

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.

Take the steps below to add an API Proxy with an OpenAPI spec.

1. Send a POST request containing the OpenAPI spec for your API to the api-docs endpoint to upload it.

   {
   "info": {
       "version": "1.0.0",
       "title": "Swagger Petstore",
       "license:" {
           "name": "MIT"
       }
   },
   "openapi": "3.0.0",
   "paths": {...}
   }
   

2. Send a POST request to the proxies endpoint to create a new API Proxy. In this example, specRef contains the name that ACM assigned to the API Docs object: petstore-1.

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

Add a Dev Portal Proxy

Next, you can add a Dev Portal Proxy to publish your API and documentation to the Developer Portal.

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

The example below adds the Developer Portal to the same API Proxy that you created in the previous section.

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

What’s Next

Congratulations! You have reached the end of the Quick Start series. We recommend taking a deeper dive into the following topics:

• Manage TLS Policies: Learn how to apply global policies to secure traffic to your Developer Portal; between your API Proxies and backend services; and between the management plane and Developer Portal hosts.
• Customize Developer Portals: Learn how to customize Developer Portals using the ACM user interface.
• Policies Overview: Learn more about the policies you can use to enforce global security or customize your backend services.