Publish Service Version
For version control of deployed APIs, leverage API7 Gateway for publishing service versions to different gateway groups, instead of in-place gateway group edits.
Typically, an API version is published first in test and staging environments before publishing in production environments. API7 Gateway manages this environmental separation through Gateway Groups, where an API belongs to a single Published Service with a shared Upstream.
This tutorial guides you in publishing the httpbin service to a gateway group on API7 Gateway. You will learn how to:
- Create a service manually and through an OpenAPI Specification file.
- Publish services by configuring upstream nodes and by using service discovery mechanisms.
Prerequisites
- Install API7 Enterprise.
- Have at least one gateway instance in your gateway group.
Add a Service Template with Routes
- Add Manually
- Import OpenAPI 3.0 Specification
- Select Service Hub from the side navigation bar, then click Add Service.
- Select Add Manually.
- From the dialog box, do the following:
- In the Name field, enter
httpbin API
. - In the Service Type field, choose
HTTP(Layer 7 Proxy)
. - In the Upstream Scheme field, choose
HTTP
. - Click Add.
- Inside the service, click Add Route.
- From the Add Route dialog box, do the following:
- In the Name field, enter
getting-started-anything
. - In the Path field, enter
/anything/*
. - In the Methods field, choose
GET
. - Click Add.
API7 Gateway supports OpenAPI v3.0. First, define your API in a YAML/JSON file as shown below:
openapi: 3.1.0
info:
title: httpbin API
description: "httpbin API for the API7 Enterprise Getting Started guides."
version: 1.0.0
paths:
"/anything/*":
get:
tags:
- Anything
summary: Returns anything that is passed into the request.
operationId: getting-started-anything
responses:
"200":
description: Successful Response
content:
application/json:
schema:
type: string
tags:
- name: Anything
description: Return anything that is passed in on the request.
Then, use it in API7 Gateway:
- Select Service Hub from the side navigation bar, then click Add Service.
- Select Import OpenAPI.
- From the dialog box, do the following:
- Upload your YAML/JSON file.
- In the Upstream Scheme field, choose
HTTP
. - Click Next.
- Confirm the following information:
- Name: the
title
field in OpenAPI Specification. - Labels: the
tag
field in OpenAPI Specification. - Description: the
description
field in OpenAPI Specification. - Routes: the
Paths
field in OpenAPI Specification. - Click Add.
Publish the Service to Gateway Group
- Publish a Single Service
- Publish Multiple Services
- Select Service Hub from the side navigation bar and then select
httpbin API
. - Click Publish New Version.
- Select your target gateway group, for example,
default
, and then click Next. - From the dialog box, do the following:
- In the New Version field, enter
1.0.0
. - In the How to find the upstream field, choose
Use Nodes
. - Click Add Node. From the dialog box, do the following:
- In the Host and Port fields, enter
httpbin.org
as the host and80
as the port. - In the Weight field, use the default value
100
. - Click Add.
- In the Host and Port fields, enter
- Confirm the service information and then click Publish.
For publishing multiple services at the same time, select Service Hub from the side navigation bar and then click Batch Publish Services.
Below is an interactive demo that provides a hands-on introduction to publishing versioned services. You will gain a better understanding of how to use it in API7 Enterprise by clicking and following the steps.
Publish the Service Using Service Discovery
Instead of configuring the upstream directly, service discovery mechanisms like Consul, Eureka, Nacos, or Kubernetes Service Discovery can be used to dynamically detect upstream nodes.
Once published, a service cannot directly switch between configured upstream nodes and service discovery. Instead, you have to configure this through a canary deployment.
- Kubernetes
- Nacos
- Select Service Registries of your gateway group from the side navigation bar, then click Add Service Registry Connection.
- From the dialog box, do the following:
- In the Name field, enter
Registry for Test
. - In the Discovery Type field, choose
Kubernetes
. - Fill in the API Server Address and Token Value field.
- Click Add.
- Wait to make sure the status of the service registry is
Healthy
. - Select Service Hub from the side navigation bar, then click Publish New Version for the
httpbin API
service. - Choose your target gateway group, for example,
default
, then click Next. - From the dialog box, do the following:
- In the New Version field, enter
1.0.0
. - In the How to find the upstream field, choose
Use Service Discovery
. - In the Service Registry field, choose
Registry for Test
, then choose the Namespace and Service Name. - Confirm the service information, then click Publish.
Below is an interactive demo that provides a hands-on introduction to connecting Kubernetes service discovery. You will gain a better understanding of how to use it in API7 Gateway by clicking and following the steps.
- Select Service Registries of your gateway group from the side navigation bar, then click Add Service Registry Connection.
- From the dialog box, do the following:
- In the Name field, enter
Registry for Test
. - In the Discovery Type field, choose
Nacos
. - In the Hosts field, fill in the host address and port.
- In the How to Get Token field, choose a way to get the token and configure related parameters.
- Click Add.
- Wait to make sure the status of the service registry is
Healthy
. - Select Service Hub from the side navigation bar, then click Publish New Version for the
httpbin API
service. - Choose your target gateway group, for example,
default
, then click Next. - From the dialog box, do the following:
- In the New Version field, enter
1.0.0
. - In the How to find the upstream field, choose
Use Service Discovery
. - In the Service Registry field, choose
Registry for Test
, then choose the Namespace, Group, and Service Name. - Confirm the service information, then click Publish.
Below is an interactive demo that provides a hands-on introduction to connecting Nacos service discovery. You will gain a better understanding of how to use it in API7 Gateway by clicking and following the steps.
Use ADC to Publish the Service
Alternatively, use ADC to configure API7 Enterprise declaratively instead of the dashboard. The complete configuration is below:
services:
- name: httpbin API
upstream:
name: default
scheme: http
nodes:
- host: httpbin.org
port: 80
weight: 100
routes:
- uris:
- /anything/*
name: getting-started-anything
description: Return anything that is passed in on the request.
methods:
- GET
Synchronize the configuration to API7 Enterprise:
adc sync -f adc.yaml
Validate the API
curl "http://127.0.0.1:9080/anything/publish"
You should see the following output:
{
"args": {},
"data": "",
"files": {},
"form": {},
"headers": {
"Accept": "*/*",
"Host": "localhost",
"User-Agent": "curl/7.88.1",
"X-Amzn-Trace-Id": "Root=1-664cc6d6-10fe9f740ab1629e19cf85a2",
"X-Forwarded-Host": "localhost"
},
"json": null,
"method": "GET",
"origin": "152.15.0.1, 116.212.249.196",
"url": "http://localhost/anything/publish"
}
Additional Resources
- Key Concepts
- Getting Started
- Best Practices