Consumer Groups Reference

Use consumer groups to manage custom rate limiting configuration for subsets of consumers.

The consumer_groups endpoint works together with the Rate Limiting Advanced plugin. To use consumer groups for rate limiting, configure the plugin with the enforce_consumer_groups and consumer_groups parameters, then use the /consumer_groups endpoint to manage the groups.

For more information and examples of setting up and managing consumer groups, see the Consumer Groups examples.

Note: Consumer groups are not supported in declarative configuration with decK. If you have consumer groups in your configuration, decK will ignore them.

List consumer groups

List all consumer groups

Endpoint

/consumer_groups

Response

HTTP/1.1 200 OK

{
    "data": [
        {
            "created_at": 1557522650,
            "id": "42b022c1-eb3c-4512-badc-1aee8c0f50b5",
            "name": "my_group"
        },
        {
            "created_at": 1637706162,
            "id": "fa6881b2-f49f-4007-9475-577cd21d34f4",
            "name": "my_group2"
        }
    ],
    "next": null
}

List a specific consumer group

Endpoint

/consumer_groups/{GROUP_NAME|GROUP_ID}

Response

HTTP/1.1 200 OK

{
    "consumer_group": {
        "created_at": 1638917780,
        "id": "be4bcfca-b1df-4fac-83cc-5cf6774bf48e",
        "name": "JL"
    }
}

List all consumers in a consumer group

Endpoint

/consumer_groups/{GROUP_NAME|GROUP_ID}/consumers

Response

HTTP/1.1 200 OK

{
    "consumers": [
        {
            "created_at": 1638918560,
            "id": "288f2bfc-04e2-4ec3-b6f3-40408dff5417",
            "type": 0,
            "username": "BarryAllen",
            "username_lower": "barryallen"
        },
        {
            "created_at": 1638915577,
            "id": "8089a0e6-1d31-4e00-bf51-5b902899b4cb",
            "type": 0,
            "username": "DianaPrince",
            "username_lower": "dianaprince"
        }
    ]
}

List consumer groups for a consumer

View all consumer groups that a consumer is assigned to.

Endpoint

/consumers/{CONSUMER_NAME|CONSUMER_ID}/consumer_groups

Response

HTTP/1.1 200 OK

{
    "consumer_groups": [
        {
            "created_at": 1638918476,
            "id": "e2c3f16e-22c7-4ef4-b6e4-ab25c522b339",
            "name": "JL"
        }
    ]
}

Create a consumer group

Endpoint

/consumer_groups

Request body

Response

HTTP 201 Created

{
  "created_at": 1557522650,
  "id": "fa6881b2-f49f-4007-9475-577cd21d34f4",
  "name": "JL",
}

Endpoint

/consumer_groups/{GROUP_NAME}

Response

HTTP 201 Created

{
  "created_at": 1557522650,
  "id": "fa6881b2-f49f-4007-9475-577cd21d34f4",
  "name": "JL",
}

Add a consumer to a group

Add a consumer to a specific consumer group.

If you add a consumer to multiple groups:

• If all groups are allowed by the Rate Limiting Advanced plugin, only the first group’s settings will apply.
• Otherwise, whichever group is specified in the Rate Limiting Advanced plugin will be active.

Consumers endpoint

/consumers/{CONSUMER_NAME|CONSUMER_ID}/consumer_groups

Request body

Response

HTTP 201 Created

{
    "consumer": {
        "created_at": 1638918560,
        "custom_id": null,
        "id": "288f2bfc-04e2-4ec3-b6f3-40408dff5417",
        "tags": null,
        "type": 0,
        "username": "BarryAllen",
        "username_lower": "barryallen"
    },
    "consumer_groups": [
        {
            "created_at": 1638918476,
            "id": "e2c3f16e-22c7-4ef4-b6e4-ab25c522b339",
            "name": "JL"
        }
    ]
}

Consumer groups endpoint

/consumer_groups/{GROUP_NAME|GROUP_ID}/consumers

Request body

Response

HTTP 201 Created

{
  "consumer_group": {
  "created_at": 1638915521,
  "id": "8a4bba3c-7f82-45f0-8121-ed4d2847c4a4",
  "name": "JL"
  },
  "consumers": [
    {
        "created_at": 1638915577,
        "id": "8089a0e6-1d31-4e00-bf51-5b902899b4cb",
        "type": 0,
        "username": "DianaPrince",
        "username_lower": "dianaprince"
    }
  ]
}

Delete a consumer group

Deleting a consumer group removes all consumers from that group. It does not delete any consumers.

Endpoint

/consumer_groups/{GROUP_NAME|GROUP_ID}

Response

HTTP/1.1 204 No Content

Remove consumers

Remove a consumer from all groups

Endpoint

/consumers/{CONSUMER_NAME|CONSUMER_ID}/consumer_groups

Response

HTTP/1.1 204 No Content

Remove a consumer from a consumer group

Consumer endpoint

/consumers/{CONSUMER_NAME|CONSUMER_ID}/consumer_groups/{GROUP_NAME|GROUP_ID}

Response

HTTP/1.1 204 No Content

Consumer groups endpoint

/consumer_groups/{GROUP_NAME|GROUP_ID}/consumers/{CONSUMER_NAME|CONSUMER_ID}

Response

HTTP/1.1 204 No Content

Remove all consumers from a consumer group

/consumer_groups/{GROUP_NAME|GROUP_ID}/consumers

Response

HTTP/1.1 204 No Content

Configure rate limiting for a consumer group

Define custom rate limiting settings for a consumer group. This endpoint overrides the settings of the Rate Limiting Advanced plugin.

/consumer_groups/{GROUP_NAME|GROUP_ID}/overrides/plugins/rate-limiting-advanced

Request Body

Response

HTTP/1.1 201 Created

{
    "config": {
        "limit": [
            10
        ],
        "retry_after_jitter_max": 0,
        "window_size": [
            10
        ],
        "window_type": "sliding"
    },
    "group": "test-group",
    "plugin": "rate-limiting-advanced"
}