Services

A service acts as a representation of a backend application or an external microservice. It essentially groups all the APIs that this application or microservice provides. Here's a breakdown of key relationships:

• Routes & Stream Routes: Most services have a one-to-many relationship with routes or stream routes(A service can only have one type: routes or stream routes). This means a single service can be associated with multiple routes or stream routes, defining how incoming API requests are directed to the appropriate functionality within the service.

• Upstreams: Typically, a service maintains a one-to-one relationship with an upstream. An upstream acts as a container, specifying the address(es) of the backend servers that handle requests for the service. To facilitate canary deployment, a service might temporarily have two upstreams: one upstream pointing to the existing backend version, and another upstream pointing to the new version being introduced.

info

For those familiar with Apache APISIX, it is important to note that the Service object in API7 Enterprise differs from the Service object in Apache APISIX.

How Services Work

The following diagram illustrates a published service that architects a Petstore service. The service has two routes with distinctive configurations. You can use the HTTP GET method to get related data.

This example directs traffic to only one upstream node. You can add more upstream nodes as required to maintain smooth operation and response while preventing single points of failure.

Service States

The service state represents the service's entire API lifecycle. A service has the template, published, or history states.

Service Template

API7 Gateway leverages service templates for version control. This optional initial state allows configuration of your API without making it live. Once finalized, publish the service template to a gateway group, assigning it a version and making the APIs accessible. Modifications to service templates do not impact existing published versions.

The Service Hub serves as a central repository for all service templates, with each template linked to its corresponding published versions.

Published Service

Published services in API7 Gateway offer accessible APIs. These services can originate from a service template (with a designated version number) or be directly created on the gateway group (no version assigned). Modifications to published services take effect immediately, impacting any ongoing traffic routed through them.

A service can have numerous versions, each with a unique number ensuring identical API behavior across gateway groups. API7 Gateway enforces a single published service version per gateway group. However, you can achieve concurrent deployments by running different service versions in separate gateway groups.

note

API7 Gateway automatically creates a service template for future version control whenever you create a published service directly on a gateway group or through the Ingress Controller.

Service History Version

In API7 Gateway, historical versions are created in two scenarios:

1. When a newer service version is published to a gateway group, or
2. When modifications are directly made to a published service (without republishing).

These historical versions remain accessible for reference, but are no longer actively handling API traffic.

Historical versions offer valuable insights into past service configurations, facilitating issue tracking and rollback capabilities. Similar to the template state, historical versions are not editable.

Service Runtime Configurations

The following configurations are classified as service runtime configurations:

• Upstreams
• Service host
• Path prefix
• Skip path prefix

It is important to note that service runtime configurations can differ even when deploying the same service version to various gateway groups. These configurations are editable directly within the gateway group, allowing for environment-specific adjustments.

note

For example, for the same service version on different gateway groups:

• The API URL in the test environment is https://api7-test.ai/v1/pet, while the node address is 127.0.0.1:80.
• The API URL in the production environment is https://api7.ai/petstore/pet, while the node address is 192.168.0.1:80.

ServiceID vs ServiceTemplateID

API7 Gateway utilizes two key identifiers for services: Service Template ID and Service ID, and similar key identifiers for routes and stream routes.

• A service template only has Service Template ID. A route/stream route in a service template only has Route Template ID/ Stream Route Template ID.
• A published service on a gateway group has both Service Template ID and Service ID at the same time for different use. A route/stream route in a published service has both Route Template ID/ Stream Route Template ID and Route ID/ Stream Route ID.
• A historical version only has Service Template ID. A route/stream route in a historical version only has Route Template ID/ Stream Route Template ID.

In contrast, Service ID is specific to a published service within a particular gateway group. You can customize this ID when creating a published service directly through the ADC, Admin API, or Ingress Controller.

It is important to note that ServiceID is only unique within its own gateway group. Two published services on different gateway groups can have the same ServiceID(not recommended). Service ID cannot be used in permission policies.

The Service Template ID is auto-generated, acts as a unique and immutable identifier that persists across all gateway groups, for service version control use. This ID applies to a service itself, including the service template, all published versions across all gateway groups, and all historical versions. It plays a vital role in permission policies, allowing you to assign resources based on the service's identity.

note

Route ID vs Route Template ID, Stream Route ID vs Stream Route Template ID are similar.

Additional Resources

• Key Concepts
  • Routes
  • Upstreams
  • Stream Routes
• Getting Started
  • Publish Services
  • Synchronize Published Service Version between Gateway Groups
• Best Practices
  • API Version Control