Consumer Groups Reference

The endpoint works together with the . 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.

Endpoint

/consumer_groups

Response

{
    "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"
    }
}

Endpoint

/consumer_groups/{GROUP_NAME|GROUP_ID}/consumers

Attribute	Description
`GROUP_NAME\|GROUP_ID` required	The name or UUID of the consumer group.

Response

HTTP/1.1 200 OK

{
    "consumers": [
        {
            "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

Attribute	Description
`USERNAME\|CONSUMER_ID` required	The name or UUID of the consumer.

Response

HTTP/1.1 200 OK

Create a consumer group

/consumer_groups

Request body

Attribute	Description
`name` required	A unique name for the consumer group you want to create.

Response

HTTP 201 Created

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

Endpoint

/consumer_groups/{GROUP_NAME}

Attribute	Description
`GROUP_NAME` required	A unique name for the consumer group you want to create.

Response

HTTP 201 Created

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

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

Attribute	Description
`group` required	The name or ID of the group to add the consumer to.

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"
    },
        {
            "created_at": 1638918476,
            "id": "e2c3f16e-22c7-4ef4-b6e4-ab25c522b339",
            "name": "JL"
        }
    ]
}

Consumer groups endpoint

/consumer_groups/{GROUP_NAME|GROUP_ID}/consumers

Attribute	Description
`GROUP_NAME\|GROUP_ID` required	The name or UUID of the consumer group.

Request body

Attribute	Description
`consumer` required	The name or ID of the consumer to add to this group.

Response

{
  "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

Endpoint

/consumer_groups/{GROUP_NAME|GROUP_ID}

Attribute	Description
`GROUP_NAME\|GROUP_ID` required	The name or UUID of the consumer group to delete.

Response

HTTP/1.1 204 No Content

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}

Attribute	Description
`CONSUMER_NAME\|CONSUMER_ID` required	The name or UUID of the consumer to remove.
`GROUP_NAME\|GROUP_ID` required	The name or UUID of the consumer group to remove the consumer from.

Response

HTTP/1.1 204 No Content

Consumer groups endpoint

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

Attribute	Description
`GROUP_NAME\|GROUP_ID` required	The name or UUID of the consumer group to remove the consumer from.
`CONSUMER_NAME\|CONSUMER_ID` required	The name or UUID of the consumer to remove.

Response

HTTP/1.1 204 No Content

/consumer_groups/{GROUP_NAME|GROUP_ID}/consumers

Attribute	Description
`GROUP_NAME\|GROUP_ID` required	The name or UUID of the consumer group to remove all consumers from.

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

Attribute	Description
`GROUP_NAME\|GROUP_ID` required	The name or UUID of the consumer group to configure.

Response

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