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.
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.
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:
- When a newer service version is published to a gateway group, or
- 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.
For example, for the same service version on different gateway groups:
- The API URL in the
testenvironment is https://api7-test.ai/v1/pet, while the node address is 127.0.0.1:80. - The API URL in the
productionenvironment 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 hasRoute Template ID/Stream Route Template ID. - A published service on a gateway group has both
Service Template IDandService IDat the same time for different use. A route/stream route in a published service has bothRoute Template ID/Stream Route Template IDandRoute ID/Stream Route ID. - A historical version only has
Service Template ID. A route/stream route in a historical version only hasRoute 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.
Route ID vs Route Template ID, Stream Route ID vs Stream Route Template ID are similar.
Additional Resource(s)
- Key Concepts
- Getting Started
- Best Practices