You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@apisix.apache.org by Jinhua Luo <lu...@gmail.com> on 2023/09/12 05:17:17 UTC
[DISCUSS] Proposal: APISIX: refactoring the admin API: make service the first-class resource
## Background
APISIX's current Admin API includes multiple resource types.
Route, upstream, and plugins are undoubtedly the three most important ones.
The routes are the traffic entries, i.e. APISIX dispatches the traffic
based on the matching conditions of the route, e.g. URI, hosts, vars.
The route is also the container for upstreams and plugins. However,
service is an optional resource type for the time being.
## Issues
In fact, based on our operating experience with dozens of companies
over the past few years, the service is a top-level concept rather
than a specific route.
However, the current Service concept does not define the correct
reference relationship, which makes the mapping from API to business a
bit obscure.
In the new design, the Service object in APISIX is a logical
abstraction for a set of upstream services. You can attach policies to
the Service object to manage access to services within.
The Service object helps ensure a more resilient and scalable
architecture. Consider a scenario where there are a few backend
replicas configured as upstream services, in communication with a
frontend application. The Service object encapsulates upstream
services into a single entity so that the frontend application does
not need to interact with upstream services or track backend changes
individually.
## Solution
In the next major version (4.x.x) of APISIX, we will adjust the
relationship between services and routes.
One of the most important changes is that we have to create the
service first, and all routes and upstreams must belong to one
service.
In this way, APISIX configuration will be more meaningful, intuitive,
and reasonable for the business.
Of course, this is a breaking change, but it's not too late to fix it
in the next major version.
### New reference relationship
```
service
`--> upstream (embedded)
`--> route (service_id) --> plugins (embedded)
`--> plugins (embedded)
```
Note that the route can also contain plugins, which will override the
plugins defined on the service, so that specific routes can be
processed specifically, for example, some APIs require authentication.
### Breaking changes in admin API
1. add service_id field in upstream cfg
2. service_id is mandatory for upstream and route
3. plugin_config will not be supported
## Demo
```
# create service first
# the upstream is embedded in the service
curl http://127.0.0.1:9180/apisix/admin/services/1 \
-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '{
"upstream": {
"nodes":[
{
"host":"httpbin.org",
"port":80,
"weight":1
},
{
"host":"postman-echo.com",
"port":80,
"weight":1
}
],
"type":"roundrobin"
}
}'
# create route within the service
# note that the service_id is mandatory!
curl http://127.0.0.1:9180/apisix/admin/routes/1 \
-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '{
"uri":"/get",
"service_id": 1
}'
# test
curl http://127.0.0.1:9080/get -v
```
Re: [DISCUSS] Proposal: APISIX: refactoring the admin API: make service the first-class resource
Posted by YuanSheng Wang <me...@apache.org>.
hi:
This is a very big change for APISIX users.
With the increasing number of APISIX users and the integration with the
surrounding ecosystem, using service as the main object is more in line
with the modern API gateway design.
I prefer this new design.
On Tue, Sep 12, 2023 at 1:17 PM Jinhua Luo <lu...@gmail.com> wrote:
> ## Background
>
> APISIX's current Admin API includes multiple resource types.
> Route, upstream, and plugins are undoubtedly the three most important ones.
> The routes are the traffic entries, i.e. APISIX dispatches the traffic
> based on the matching conditions of the route, e.g. URI, hosts, vars.
> The route is also the container for upstreams and plugins. However,
> service is an optional resource type for the time being.
>
> ## Issues
>
> In fact, based on our operating experience with dozens of companies
> over the past few years, the service is a top-level concept rather
> than a specific route.
>
> However, the current Service concept does not define the correct
> reference relationship, which makes the mapping from API to business a
> bit obscure.
>
> In the new design, the Service object in APISIX is a logical
> abstraction for a set of upstream services. You can attach policies to
> the Service object to manage access to services within.
>
> The Service object helps ensure a more resilient and scalable
> architecture. Consider a scenario where there are a few backend
> replicas configured as upstream services, in communication with a
> frontend application. The Service object encapsulates upstream
> services into a single entity so that the frontend application does
> not need to interact with upstream services or track backend changes
> individually.
>
> ## Solution
>
> In the next major version (4.x.x) of APISIX, we will adjust the
> relationship between services and routes.
> One of the most important changes is that we have to create the
> service first, and all routes and upstreams must belong to one
> service.
> In this way, APISIX configuration will be more meaningful, intuitive,
> and reasonable for the business.
> Of course, this is a breaking change, but it's not too late to fix it
> in the next major version.
>
> ### New reference relationship
>
> ```
> service
> `--> upstream (embedded)
> `--> route (service_id) --> plugins (embedded)
> `--> plugins (embedded)
> ```
>
> Note that the route can also contain plugins, which will override the
> plugins defined on the service, so that specific routes can be
> processed specifically, for example, some APIs require authentication.
>
> ### Breaking changes in admin API
>
> 1. add service_id field in upstream cfg
> 2. service_id is mandatory for upstream and route
> 3. plugin_config will not be supported
>
> ## Demo
>
> ```
> # create service first
> # the upstream is embedded in the service
> curl http://127.0.0.1:9180/apisix/admin/services/1 \
> -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '{
> "upstream": {
> "nodes":[
> {
> "host":"httpbin.org",
> "port":80,
> "weight":1
> },
> {
> "host":"postman-echo.com",
> "port":80,
> "weight":1
> }
> ],
> "type":"roundrobin"
> }
> }'
>
> # create route within the service
> # note that the service_id is mandatory!
> curl http://127.0.0.1:9180/apisix/admin/routes/1 \
> -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '{
> "uri":"/get",
> "service_id": 1
> }'
>
> # test
> curl http://127.0.0.1:9080/get -v
> ```
>
--
*MembPhis*
My GitHub: https://github.com/membphis
Apache APISIX: https://github.com/apache/apisix