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:

1. Create a service manually and through an OpenAPI Specification file.
2. Publish services by configuring upstream nodes and by using service discovery mechanisms.

Prerequisites

1. Install API7 Enterprise.
2. Have at least one gateway instance in your gateway group.

Add a Service Template with Routes

Add Manually

You can either use the dashboard or ADC to add a service manually.

Dashboard

1. Select Service Hub from the side navigation bar, then click Add Service.
2. Select Add Manually.
3. From the dialog box, do the following:

• In the Name field, enter httpbin.
• In the Service Type field, choose HTTP(Layer 7 Proxy).
• In the Upstream Scheme field, choose HTTP.
• Click Add.

4. Inside the service, click Add Route.
5. 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.

ADC

Create an ADC configuration file with the service and the upstream configuration:

adc.yaml

services:
  - name: httpbin
    upstream:
      name: httpbin upstream
      scheme: http
      nodes:
        - host: httpbin.org
          port: 80
          weight: 100
    routes:
      - uris:
          - /anything/*
        name: getting-started-anything
        methods:
          - GET

Import OpenAPI 3.0 Specification

Both the dashboard and ADC support importing an OpenAPI v3.0 Specification.

Dashboard

Define your API in a YAML/JSON file as shown below:

OpenAPI.yaml

openapi: 3.1.0
info:
  title: httpbin
  description: "httpbin 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:

1. Select Service Hub from the side navigation bar, then click Add Service.
2. Select Import OpenAPI.
3. From the dialog box, do the following:

• Upload your YAML/JSON file.
• In the Upstream Scheme field, choose HTTP.
• Click Next.

4. 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.

ADC

Define your API in a YAML/JSON file as shown below:

openapi.yaml

openapi: 3.1.0
info:
  title: httpbin
  description: "httpbin for the API7 Enterprise Getting Started guides."
  version: 1.0.0
servers:
  - url: http://httpbin.org:80
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.

Use ADC to convert the OpenAPI Specification to an ADC configuration file:

adc convert openapi -f openapi.yaml -o adc.yaml

Publish the Service to Gateway Group

Publish a Single Service

You can either use the dashboard or ADC to publish a service.

Dashboard

1. Select Service Hub from the side navigation bar and then select httpbin.
2. Click Publish New Version.
3. Select your target gateway group, for example, default, and then click Next.
4. 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 and 80 as the port.
  • In the Weight field, use the default value 100.
  • Click Add.
• Confirm the service information and then click Publish.

ADC

Synchronize the configuration file created in the previous step to your target gateway group, for example, default:

adc sync -f adc.yaml --gateway-group default

Publish Multiple Services

You can either use the dashboard or ADC to publish multiple services.

Dashboard

1. Select Service Hub from the side navigation bar and then click Batch Publish Services.
2. Select your target gateway group, for example, default, and then click Next.
3. Click Add Service.
4. From the dialog box, do the following:

• In the Service dropdown, select the service you want to publish.
• In the New Version field, enter 1.0.0.
• Click Add.

5. Repeat the above steps to add more services.
6. Click Next to continue publishing the services.
7. In the new window, do the following for each service:

• 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 and 80 as the port.
  • In the Weight field, use the default value 100.
  • Click Add.

8. Confirm the information and then click Publish.

ADC

To publish multiple services, you can either update your ADC configuration file to include other services or use multiple configuration files and synchronize them to your target gateway group, for example, default, as shown below:

adc sync -f adc-1.yaml -f adc-2.yaml

Below is an interactive demo that provides a hands-on introduction to publish 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.

info

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

1. Select Service Registries of your gateway group from the side navigation bar, then click Add Service Registry Connection.
2. 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.

4. Wait to make sure the status of the service registry is Healthy.
5. Select Service Hub from the side navigation bar, then click Publish New Version for the httpbin service.
6. Choose your target gateway group, for example, default, then click Next.
7. 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.

Nacos

1. Select Service Registries of your gateway group from the side navigation bar, then click Add Service Registry Connection.
2. 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.

4. Wait to make sure the status of the service registry is Healthy.
5. Select Service Hub from the side navigation bar, then click Publish New Version for the httpbin service.
6. Choose your target gateway group, for example, default, then click Next.
7. 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.

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
  • Services
• Getting Started
  • Synchronize Published Service Version between Gateway Groups
  • Rollback a Published Service
• Best Practices
  • API Version Control