Initial commit
This commit is contained in:
Zhongwei Li
360
references/rate-limiting-filtering.md
Normal file
360
references/rate-limiting-filtering.md
Normal file
@@ -0,0 +1,360 @@
|
||||
# Rate Limiting and Filtering Reference
|
||||
|
||||
Complete reference for SAP Service Manager API rate limits and query filtering.
|
||||
|
||||
**Documentation**: [https://github.com/SAP-docs/sap-btp-service-manager/tree/main/docs/Service-Consumption/SAP-Service-Manager](https://github.com/SAP-docs/sap-btp-service-manager/tree/main/docs/Service-Consumption/SAP-Service-Manager)
|
||||
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Rate Limiting](#rate-limiting)
|
||||
- [Identification](#identification)
|
||||
- [Level 1: All APIs Combined](#level-1-all-apis-combined)
|
||||
- [Level 2: Resource-Specific Limits](#level-2-resource-specific-limits)
|
||||
- [Level 3: Instance Operations](#level-3-instance-operations)
|
||||
- [HTTP 429 Responses](#http-429-responses)
|
||||
2. [Query Filtering](#query-filtering)
|
||||
- [Field Filtering](#field-filtering)
|
||||
- [Label Filtering](#label-filtering)
|
||||
- [Operators](#operators)
|
||||
- [Combining Filters](#combining-filters)
|
||||
3. [Best Practices](#best-practices)
|
||||
- [Rate Limit Handling](#rate-limit-handling)
|
||||
- [Filter Optimization](#filter-optimization)
|
||||
4. [Examples](#examples)
|
||||
- [Common Query Patterns](#common-query-patterns)
|
||||
- [Rate Limit Scenarios](#rate-limit-scenarios)
|
||||
|
||||
---
|
||||
|
||||
## Rate Limiting
|
||||
|
||||
SAP Service Manager implements **three concurrent rate limiting levels**. Exceeding any tier triggers throttling, even if other allowances remain.
|
||||
|
||||
### Identification
|
||||
|
||||
Callers identified by:
|
||||
- Username (for user tokens)
|
||||
- OAuth Client ID (for client tokens)
|
||||
|
||||
### Level 1: All APIs Combined
|
||||
|
||||
| Limit Type | Value |
|
||||
|------------|-------|
|
||||
| Per Hour | 10,000 requests |
|
||||
| Per Minute | 1,000 requests |
|
||||
|
||||
Applies to all API endpoints combined.
|
||||
|
||||
---
|
||||
|
||||
### Level 2: Resource-Specific Limits
|
||||
|
||||
| Endpoint | Per Hour | Per Minute |
|
||||
|----------|----------|------------|
|
||||
| `/v1/service_bindings` | 6,000 | 600 |
|
||||
| `/v1/service_offerings` | 1,000 | 100 |
|
||||
| `/v1/service_plans` | 1,000 | 100 |
|
||||
|
||||
---
|
||||
|
||||
### Level 3: Method-Specific Limits
|
||||
|
||||
| Operation | Endpoint | Per Hour | Per Minute |
|
||||
|-----------|----------|----------|------------|
|
||||
| CREATE | `/v1/service_instances` | - | 50 |
|
||||
| UPDATE | `/v1/service_instances` | 6,000 | 600 |
|
||||
| DELETE | `/v1/service_instances` | 6,000 | 600 |
|
||||
|
||||
**Note**: CREATE has a stricter minute limit (50/min) to prevent provisioning storms.
|
||||
|
||||
---
|
||||
|
||||
### Rate Limit Error Response
|
||||
|
||||
**HTTP Status**: `429 Too Many Requests`
|
||||
|
||||
**Response Headers**:
|
||||
| Header | Description |
|
||||
|--------|-------------|
|
||||
| `Retry-After` | When to retry (HTTP-date format) |
|
||||
|
||||
**HTTP-date Format**: `Sun, 06 Nov 1994 08:49:37 GMT`
|
||||
|
||||
**Example Response**:
|
||||
```json
|
||||
{
|
||||
"error": "rate_limit_exceeded",
|
||||
"description": "Request rate limit exceeded. Please retry after the time specified in the Retry-After header."
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Best Practices for Rate Limits
|
||||
|
||||
1. **Implement Exponential Backoff**:
|
||||
```javascript
|
||||
async function withRetry(fn, maxRetries = 5) {
|
||||
for (let i = 0; i < maxRetries; i++) {
|
||||
try {
|
||||
return await fn();
|
||||
} catch (error) {
|
||||
if (error.status === 429) {
|
||||
const retryAfter = error.headers['retry-after'];
|
||||
const waitTime = retryAfter ?
|
||||
new Date(retryAfter) - Date.now() :
|
||||
Math.pow(2, i) * 1000;
|
||||
await sleep(waitTime);
|
||||
} else {
|
||||
throw error;
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
2. **Batch Operations**: Group related operations where possible
|
||||
|
||||
3. **Cache Responses**: Cache listing responses (offerings, plans)
|
||||
|
||||
4. **Stagger Requests**: Distribute requests over time
|
||||
|
||||
5. **Monitor Usage**: Track request counts to stay within limits
|
||||
|
||||
---
|
||||
|
||||
## Filtering
|
||||
|
||||
The SAP Service Manager APIs support filtering via query parameters on GET (list) endpoints.
|
||||
|
||||
### Query Parameter Types
|
||||
|
||||
| Parameter | Purpose | Example |
|
||||
|-----------|---------|---------|
|
||||
| `fieldQuery` | Filter by field values | `type eq 'kubernetes'` |
|
||||
| `labelQuery` | Filter by label values | `environment eq 'dev'` |
|
||||
|
||||
Both can be combined; results must match both criteria.
|
||||
|
||||
---
|
||||
|
||||
### Supported Literal Types
|
||||
|
||||
| Type | Format | Example |
|
||||
|------|--------|---------|
|
||||
| String | Single quotes | `'my-value'` |
|
||||
| Boolean | Unquoted | `true`, `false` |
|
||||
| Integer | Digits with optional sign | `42`, `-7`, `+100` |
|
||||
| Date-time | ISO 8601 | `2025-01-15T10:30:00Z` |
|
||||
|
||||
**String Escaping**: Double single quotes for embedded quotes (`'it''s valid'`)
|
||||
|
||||
---
|
||||
|
||||
### Field Query Operators
|
||||
|
||||
#### Universal Operators (Field & Label Queries)
|
||||
|
||||
| Operator | Description | Example |
|
||||
|----------|-------------|---------|
|
||||
| `eq` | Equal | `name eq 'my-instance'` |
|
||||
| `en` | Equal or null | `broker_id en 'abc-123'` |
|
||||
| `ne` | Not equal | `type ne 'kubernetes'` |
|
||||
| `in` | In list | `plan_name in ('small','medium')` |
|
||||
| `notin` | Not in list | `status notin ('failed','pending')` |
|
||||
| `and` | Logical AND | `type eq 'cf' and ready eq true` |
|
||||
| `contains` | Substring match | `name contains 'prod'` |
|
||||
|
||||
#### Field-Only Operators
|
||||
|
||||
| Operator | Description | Example |
|
||||
|----------|-------------|---------|
|
||||
| `gt` | Greater than | `created_at gt '2025-01-01T00:00:00Z'` |
|
||||
| `ge` | Greater than or equal | `version ge 2` |
|
||||
| `lt` | Less than | `updated_at lt '2025-06-01T00:00:00Z'` |
|
||||
| `le` | Less than or equal | `retries le 3` |
|
||||
|
||||
---
|
||||
|
||||
### Filterable Resources
|
||||
|
||||
| Resource | Supports fieldQuery | Supports labelQuery |
|
||||
|----------|---------------------|---------------------|
|
||||
| Platforms | Yes | Yes |
|
||||
| Service Brokers | Yes | Yes |
|
||||
| Service Instances | Yes | Yes |
|
||||
| Service Bindings | Yes | Yes |
|
||||
| Service Plans | Yes | No |
|
||||
| Service Offerings | Yes | No |
|
||||
|
||||
---
|
||||
|
||||
### Common Field Names
|
||||
|
||||
#### Service Instances
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `id` | String | Instance ID |
|
||||
| `name` | String | Instance name |
|
||||
| `service_plan_id` | String | Plan ID |
|
||||
| `platform_id` | String | Platform ID |
|
||||
| `ready` | Boolean | Readiness status |
|
||||
| `usable` | Boolean | Usability status |
|
||||
| `created_at` | DateTime | Creation timestamp |
|
||||
| `updated_at` | DateTime | Last update timestamp |
|
||||
|
||||
#### Service Bindings
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `id` | String | Binding ID |
|
||||
| `name` | String | Binding name |
|
||||
| `service_instance_id` | String | Associated instance |
|
||||
| `ready` | Boolean | Readiness status |
|
||||
| `created_at` | DateTime | Creation timestamp |
|
||||
|
||||
#### Platforms
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `id` | String | Platform ID |
|
||||
| `name` | String | Platform name |
|
||||
| `type` | String | Platform type |
|
||||
|
||||
---
|
||||
|
||||
### Query Examples
|
||||
|
||||
#### Single Field Filter
|
||||
|
||||
```
|
||||
GET /v1/service_instances?fieldQuery=ready eq true
|
||||
```
|
||||
|
||||
#### Multiple Conditions (AND)
|
||||
|
||||
```
|
||||
GET /v1/service_instances?fieldQuery=ready eq true and usable eq true
|
||||
```
|
||||
|
||||
#### In List
|
||||
|
||||
```
|
||||
GET /v1/service_instances?fieldQuery=service_plan_id in ('plan-1','plan-2','plan-3')
|
||||
```
|
||||
|
||||
#### Date Range
|
||||
|
||||
```
|
||||
GET /v1/service_instances?fieldQuery=created_at gt '2025-01-01T00:00:00Z' and created_at lt '2025-02-01T00:00:00Z'
|
||||
```
|
||||
|
||||
#### String Contains
|
||||
|
||||
```
|
||||
GET /v1/service_instances?fieldQuery=name contains 'production'
|
||||
```
|
||||
|
||||
#### Label Query
|
||||
|
||||
```
|
||||
GET /v1/service_instances?labelQuery=environment eq 'production'
|
||||
```
|
||||
|
||||
#### Combined Field and Label Query
|
||||
|
||||
```
|
||||
GET /v1/service_instances?fieldQuery=ready eq true&labelQuery=team eq 'platform'
|
||||
```
|
||||
|
||||
#### Complex Query
|
||||
|
||||
```
|
||||
GET /v1/service_instances?fieldQuery=broker_id eq 'abc-123' and plan_name in ('small','medium') and ready eq true&labelQuery=environment eq 'dev'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### URL Encoding
|
||||
|
||||
Special characters must be URL-encoded:
|
||||
|
||||
| Character | Encoded |
|
||||
|-----------|---------|
|
||||
| Space | `%20` or `+` |
|
||||
| Single quote | `%27` |
|
||||
| Comma | `%2C` |
|
||||
| Colon | `%3A` |
|
||||
|
||||
**Example**:
|
||||
```
|
||||
# Original
|
||||
fieldQuery=name eq 'my instance'
|
||||
|
||||
# Encoded
|
||||
fieldQuery=name%20eq%20%27my%20instance%27
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Pagination
|
||||
|
||||
List endpoints support pagination:
|
||||
|
||||
| Parameter | Description |
|
||||
|-----------|-------------|
|
||||
| `max_items` | Maximum results per page |
|
||||
| `token` | Continuation token |
|
||||
|
||||
**Response**:
|
||||
```json
|
||||
{
|
||||
"items": [...],
|
||||
"num_items": 50,
|
||||
"token": "next-page-token"
|
||||
}
|
||||
```
|
||||
|
||||
**Usage**:
|
||||
```
|
||||
GET /v1/service_instances?max_items=50
|
||||
GET /v1/service_instances?max_items=50&token=<token-from-previous>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Syntax Rules
|
||||
|
||||
1. **String literals** require single quotes
|
||||
2. **Boolean literals** must not be quoted
|
||||
3. **Literals cannot use brackets** (except in `in`/`notin` lists)
|
||||
4. **Embedded quotes** use double single quotes (`''`)
|
||||
5. **Whitespace** around operators is optional but recommended
|
||||
6. **Case sensitivity**: Field names are case-sensitive
|
||||
|
||||
---
|
||||
|
||||
### Error Handling
|
||||
|
||||
**Invalid Query Syntax**:
|
||||
```json
|
||||
{
|
||||
"error": "InvalidQuery",
|
||||
"description": "Invalid fieldQuery syntax at position 15"
|
||||
}
|
||||
```
|
||||
|
||||
**Unknown Field**:
|
||||
```json
|
||||
{
|
||||
"error": "InvalidField",
|
||||
"description": "Field 'invalid_field' is not supported for filtering"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Documentation Links
|
||||
|
||||
- **Rate Limiting**: [https://github.com/SAP-docs/sap-btp-service-manager/blob/main/docs/Service-Consumption/SAP-Service-Manager/rate-limiting-97be679.md](https://github.com/SAP-docs/sap-btp-service-manager/blob/main/docs/Service-Consumption/SAP-Service-Manager/rate-limiting-97be679.md)
|
||||
- **Filtering**: [https://github.com/SAP-docs/sap-btp-service-manager/blob/main/docs/Service-Consumption/SAP-Service-Manager/filtering-parameters-and-operators-3331c6e.md](https://github.com/SAP-docs/sap-btp-service-manager/blob/main/docs/Service-Consumption/SAP-Service-Manager/filtering-parameters-and-operators-3331c6e.md)
|
||||
Reference in New Issue
Block a user