Skip to main content



A service represents a backend application or an external microservice, and contains all the APIs that application provides. In general, services have a one-to-many relationship with routes, and a one-to-one relationship with upstreams. However, a service will temporarily have two upstreams for a traffic canary process.

The following diagram illustrates a published service that architects a pet store (store) backend at Foodbar Company (a fictional company). 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. For details, see ensure upstream high availability.

You can also use service discovery to dynamically get the latest upstream nodes.

Service States

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


The template state is the initial state, representing the latest unpublished draft configuration. APIs in the template state are not accessible and do not have a specific version number.


An active version with a unique version number is created when you publish a template to a gateway group. Published versions contain accessible APIs that are tied to the gateway group. You can only edit service runtime configurations (host, path prefix, and upstream nodes).

To update live APIs, a new version must be published. A service can have multiple versions but the version number is unique, which guarantees identical API configurations across gateway groups. Template changes do not affect published versions.


When a new version is published, the previous versions are historical versions. A service cannot simultaneously have two active versions in one gateway group, but can run different versions concurrently in different gateway groups.

Historical versions provide visibility into past configurations to track issue. Like in the template state, you cannot edit service configurations in history state. Historical versions are mainly used for emergency rollbacks.

History versions do not include service runtime configurations. Existing values are retained during rollbacks.

Service Runtime Configurations

The following configurations are classified as service runtime configurations:

  • Upstream nodes
  • Service discovery
  • Service host
  • Path prefix

These service runtime configurations may vary when the same service version is published to different gateway groups, and you can edit them directly within the gateway group.


For example: Logo

API Management for Modern Architectures with Edge, API Gateway, Kubernetes, and Service Mesh.


API7 Cloud

SOC2 Type IRed Herring

Copyright © APISEVEN Ltd. 2019 – 2024. Apache, Apache APISIX, APISIX, and associated open source project names are trademarks of the

Apache Software Foundation