service.md

title
Service

Description

A Service is an abstraction of an API (which can also be understood as a set of Route abstractions). It usually corresponds to an upstream service abstraction.

The relationship between Routes and a Service is usually N:1 as shown in the image below.

As shown, different Routes could be bound to the same Service. This reduces redundancy as these bounded Routes will have the same Upstream and Plugin configurations.

For more information about Service, please refer to Admin API Service object.

Examples

The following example creates a Service that enables the limit-count Plugin and then binds it to the Routes with the ids 100 and 101.

:::note You can fetch the admin_key from config.yaml and save to an environment variable with the following command:

admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"//g')

:::

1. Create a Service.

curl http://127.0.0.1:9180/apisix/admin/services/200 \
-H "X-API-KEY: $admin_key" -X PUT -d '
{
    "plugins": {
        "limit-count": {
            "count": 2,
            "time_window": 60,
            "rejected_code": 503,
            "key": "remote_addr"
        }
    },
    "upstream": {
        "type": "roundrobin",
        "nodes": {
            "127.0.0.1:1980": 1
        }
    }
}'

2. create new Route and reference the service by id 200

   curl http://127.0.0.1:9180/apisix/admin/routes/100 \
   -H "X-API-KEY: $admin_key" -X PUT -d '
   {
       "methods": ["GET"],
       "uri": "/index.html",
       "service_id": "200"
   }'

   curl http://127.0.0.1:9180/apisix/admin/routes/101 \
   -H "X-API-KEY: $admin_key" -X PUT -d '
   {
       "methods": ["GET"],
       "uri": "/foo/index.html",
       "service_id": "200"
   }'

We can also specify different Plugins or Upstream for the Routes than the ones defined in the Service. The example below creates a Route with a limit-count Plugin. This Route will continue to use the other configurations defined in the Service (here, the Upstream configuration).

```shell
curl http://127.0.0.1:9180/apisix/admin/routes/102 \
-H "X-API-KEY: $admin_key" -X PUT -d '
{
    "uri": "/bar/index.html",
    "id": "102",
    "service_id": "200",
    "plugins": {
        "limit-count": {
            "count": 2000,
            "time_window": 60,
            "rejected_code": 503,
            "key": "remote_addr"
        }
    }
}'
```

:::note

When a Route and a Service enable the same Plugin, the one defined in the Route is given the higher priority.

:::