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 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:
Add a Services Workspace
First, create a Services Workspace. This is a team space where you can manage the API’s lifecycle.
Method | Endpoint |
---|---|
POST | /services/workspaces |
{
"name": "{{proxyWorkspaceName}}",
"metadata": {
"description": "🏎️ F1 Workspace"
},
"contactDetails": {
"adminEmail": "daniel@f1.test",
"adminName": "Daniel Ricardo",
"adminPhone": "086 555 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.
Method | Endpoint |
---|---|
POST | /services/workspaces/{{proxyWorkspaceName}}/proxies |
API Proxy without OpenAPI Spec
The basic configuration below creates an API Proxy to the backend service hosted at ergast.com
.
{
"name": "{{proxyName}}",
"metadata": {
"description": "🏎️ F1 Proxy"
},
"version": "v1",
"proxyConfig": {
"hostname": "{{environmentHostname}}",
"ingress": {
"basePath": "/api/f1",
},
"backends": [
{
"serviceName": "f1-api-svc",
"serviceTargets": [
{
"hostname": "ergast.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.
For the example F1 Results API, the auto-generated name for the API Docs would be f1-results-api-v1
.
Method | Endpoint |
---|---|
POST | /services/workspaces/{{proxyWorkspaceName}}/api-docs |
POST | /services/workspaces/{{proxyWorkspaceName}}/proxies |
Example OpenAPI spec: f1-api.json
Take the steps below to add an API Proxy with an OpenAPI spec.
-
Send a POST request containing the OpenAPI spec for your API to the
api-docs
endpoint to upload it.{ "info": { "license": { "name": "MIT" }, "title": "F1 Results API", "version": "v1" }, "openapi": "3.0.0", "paths": {...} }
-
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:f1-results-api-1
.{ "name": "{{proxyName}}", "metadata": { "description": "🏎️ F1 Proxy" }, "version": "v1", "specRef": "f1-results-api-1", "proxyConfig": { "hostname": "{{environmentHostname}}", "ingress": { "basePath": "/api/f1", }, "backends": [ { "serviceName": "f1-api-svc", "serviceTargets": [ { "hostname": "ergast.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.
Method | Endpoint |
---|---|
PUT | /services/workspaces/{{proxyWorkspaceName}}/proxies/{{proxyName}} |
The example below adds the Developer Portal to the same API Proxy that you created in the previous section.
{
"name": "{{proxyName}}",
"specRef": "f1-results-api-1",
"proxyConfig": {
"hostname": "{{environmentHostname}}",
"ingress": {
"basePath": "/api/f1"
},
"backends": [
{
"serviceName": "f1-service",
"serviceTargets": [
{
"hostname": "ergast.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.