0
# API Definition System
1

2
The API Definition System provides a flexible framework for defining and managing gateway API groups using predicates. This system enables fine-grained control over which requests match specific API definitions for flow control and monitoring purposes.
3

4
## Capabilities
5

6
### ApiDefinition
7

8
Core class representing a group of HTTP API patterns with associated predicates for request matching.
9

10
```java { .api }
11
/**
12
 * Represents a group of HTTP API patterns for gateway routing and flow control
13
 */
14
class ApiDefinition {
15
    /** Default constructor */
16
    ApiDefinition();
17
    
18
    /** Constructor with API name */
19
    ApiDefinition(String apiName);
20
    
21
    /** Get the API group name */
22
    String getApiName();
23
    
24
    /** Set the API group name (fluent interface) */
25
    ApiDefinition setApiName(String apiName);
26
    
27
    /** Get the set of predicate items that define this API group */
28
    Set<ApiPredicateItem> getPredicateItems();
29
    
30
    /** Set the predicate items for this API group (fluent interface) */
31
    ApiDefinition setPredicateItems(Set<ApiPredicateItem> predicateItems);
32
}
33
```
34

35
**Usage Examples:**
36

37
```java
38
import com.alibaba.csp.sentinel.adapter.gateway.common.api.*;
39

40
// Create API definition with name
41
ApiDefinition userApi = new ApiDefinition("user-service");
42

43
// Create with fluent interface
44
ApiDefinition orderApi = new ApiDefinition()
45
    .setApiName("order-service")
46
    .setPredicateItems(Set.of(
47
        new ApiPathPredicateItem()
48
            .setPattern("/api/orders/**")
49
            .setMatchStrategy(SentinelGatewayConstants.URL_MATCH_STRATEGY_PREFIX)
50
    ));
51
```
52

53
### ApiPredicateItem
54

55
Base interface for API predicate conditions that determine when requests match an API definition.
56

57
```java { .api }
58
/**
59
 * Base interface for API predicate conditions
60
 */
61
interface ApiPredicateItem {
62
    // Marker interface for API matching predicates
63
}
64
```
65

66
### ApiPathPredicateItem
67

68
Path-based predicate implementation for matching requests by URL path patterns.
69

70
```java { .api }
71
/**
72
 * Path-based predicate for API matching using URL patterns
73
 */
74
class ApiPathPredicateItem implements ApiPredicateItem {
75
    /** Get the URL pattern for matching */
76
    String getPattern();
77
    
78
    /** Set the URL pattern (fluent interface) */
79
    ApiPathPredicateItem setPattern(String pattern);
80
    
81
    /** Get the matching strategy (exact/prefix/regex) */
82
    int getMatchStrategy();
83
    
84
    /** Set the matching strategy (fluent interface) */
85
    ApiPathPredicateItem setMatchStrategy(int matchStrategy);
86
}
87
```
88

89
**Usage Examples:**
90

91
```java
92
// Exact path matching
93
ApiPathPredicateItem exactMatch = new ApiPathPredicateItem()
94
    .setPattern("/api/users/profile")
95
    .setMatchStrategy(SentinelGatewayConstants.URL_MATCH_STRATEGY_EXACT);
96

97
// Prefix matching for all user-related endpoints
98
ApiPathPredicateItem prefixMatch = new ApiPathPredicateItem()
99
    .setPattern("/api/users")
100
    .setMatchStrategy(SentinelGatewayConstants.URL_MATCH_STRATEGY_PREFIX);
101

102
// Regex matching for complex patterns
103
ApiPathPredicateItem regexMatch = new ApiPathPredicateItem()
104
    .setPattern("/api/users/\\d+/orders")
105
    .setMatchStrategy(SentinelGatewayConstants.URL_MATCH_STRATEGY_REGEX);
106
```
107

108
### ApiPredicateGroupItem
109

110
Groups multiple predicate items together for complex API matching logic.
111

112
```java { .api }
113
/**
114
 * Groups multiple predicate items together for complex matching
115
 */
116
class ApiPredicateGroupItem implements ApiPredicateItem {
117
    /** Add a predicate item to this group (fluent interface) */
118
    ApiPredicateGroupItem addItem(ApiPredicateItem item);
119
    
120
    /** Get all predicate items in this group */
121
    Set<ApiPredicateItem> getItems();
122
}
123
```
124

125
**Usage Examples:**
126

127
```java
128
// Group multiple path patterns
129
ApiPredicateGroupItem userApiGroup = new ApiPredicateGroupItem()
130
    .addItem(new ApiPathPredicateItem()
131
        .setPattern("/api/users/**")
132
        .setMatchStrategy(SentinelGatewayConstants.URL_MATCH_STRATEGY_PREFIX))
133
    .addItem(new ApiPathPredicateItem()
134
        .setPattern("/api/user-profile/**")
135
        .setMatchStrategy(SentinelGatewayConstants.URL_MATCH_STRATEGY_PREFIX));
136
```
137

138
### GatewayApiDefinitionManager
139

140
Manager class providing centralized management of API definitions with property-based configuration and observer pattern support.
141

142
```java { .api }
143
/**
144
 * Manager for gateway API definitions with property binding and observer pattern
145
 */
146
final class GatewayApiDefinitionManager {
147
    /** Register a property for API definition updates */
148
    static void register2Property(SentinelProperty<Set<ApiDefinition>> property);
149
    
150
    /** Load a set of API definitions, replacing existing ones */
151
    static boolean loadApiDefinitions(Set<ApiDefinition> apiDefinitions);
152
    
153
    /** Get a specific API definition by name */
154
    static ApiDefinition getApiDefinition(String apiName);
155
    
156
    /** Get all currently loaded API definitions */
157
    static Set<ApiDefinition> getApiDefinitions();
158
    
159
    /** Validate if an API definition is properly configured */
160
    static boolean isValidApi(ApiDefinition apiDefinition);
161
}
162
```
163

164
**Usage Examples:**
165

166
```java
167
import com.alibaba.csp.sentinel.adapter.gateway.common.api.*;
168
import java.util.Set;
169

170
// Create multiple API definitions
171
Set<ApiDefinition> apiDefinitions = Set.of(
172
    new ApiDefinition("user-api")
173
        .setPredicateItems(Set.of(
174
            new ApiPathPredicateItem()
175
                .setPattern("/api/users/**")
176
                .setMatchStrategy(SentinelGatewayConstants.URL_MATCH_STRATEGY_PREFIX)
177
        )),
178
    new ApiDefinition("order-api")
179
        .setPredicateItems(Set.of(
180
            new ApiPathPredicateItem()
181
                .setPattern("/api/orders/**")
182
                .setMatchStrategy(SentinelGatewayConstants.URL_MATCH_STRATEGY_PREFIX)
183
        ))
184
);
185

186
// Load API definitions
187
boolean loaded = GatewayApiDefinitionManager.loadApiDefinitions(apiDefinitions);
188

189
// Retrieve specific API definition
190
ApiDefinition userApi = GatewayApiDefinitionManager.getApiDefinition("user-api");
191

192
// Get all loaded definitions
193
Set<ApiDefinition> allApis = GatewayApiDefinitionManager.getApiDefinitions();
194

195
// Validate API definition
196
ApiDefinition testApi = new ApiDefinition("test-api");
197
boolean isValid = GatewayApiDefinitionManager.isValidApi(testApi); // false - missing predicates
198
```
199

200
### ApiDefinitionChangeObserver
201

202
Observer interface for receiving notifications when API definitions change.
203

204
```java { .api }
205
/**
206
 * Observer interface for API definition changes
207
 */
208
interface ApiDefinitionChangeObserver {
209
    /** Called when API definitions change */
210
    void onChange(Set<ApiDefinition> apiDefinitions);
211
}
212
```
213

214
**Usage Examples:**
215

216
```java
217
// Custom observer implementation
218
public class MyApiChangeObserver implements ApiDefinitionChangeObserver {
219
    @Override
220
    public void onChange(Set<ApiDefinition> apiDefinitions) {
221
        System.out.println("API definitions updated: " + apiDefinitions.size() + " definitions");
222
        // Handle API definition changes (e.g., refresh caches, update configurations)
223
    }
224
}
225
```
226

227
### AbstractApiMatcher
228

229
Base class for implementing custom API matchers with predicate logic.
230

231
```java { .api }
232
/**
233
 * Base class for API matchers with predicate logic
234
 * @param <T> Type of request object to match against
235
 */
236
abstract class AbstractApiMatcher<T> implements Predicate<T> {
237
    /** Constructor with API definition */
238
    AbstractApiMatcher(ApiDefinition apiDefinition);
239
    
240
    /** Get the API name this matcher handles */
241
    String getApiName();
242
    
243
    /** Get the API definition this matcher uses */
244
    ApiDefinition getApiDefinition();
245
    
246
    /** Test if the request matches this API (from Predicate interface) */
247
    boolean test(T request);
248
    
249
    /** Initialize the matchers - must be implemented by subclasses */
250
    protected abstract void initializeMatchers();
251
}
252
```
253

254
**Usage Examples:**
255

256
```java
257
// Custom matcher implementation
258
public class HttpRequestApiMatcher extends AbstractApiMatcher<HttpServletRequest> {
259
    public HttpRequestApiMatcher(ApiDefinition apiDefinition) {
260
        super(apiDefinition);
261
    }
262
    
263
    @Override
264
    protected void initializeMatchers() {
265
        // Initialize custom matching logic based on API definition predicates
266
    }
267
    
268
    // test() method is implemented by the base class using initializeMatchers()
269
}
270

271
// Usage
272
ApiDefinition userApi = new ApiDefinition("user-api")
273
    .setPredicateItems(Set.of(
274
        new ApiPathPredicateItem()
275
            .setPattern("/api/users/**")
276
            .setMatchStrategy(SentinelGatewayConstants.URL_MATCH_STRATEGY_PREFIX)
277
    ));
278

279
HttpRequestApiMatcher matcher = new HttpRequestApiMatcher(userApi);
280
boolean matches = matcher.test(httpRequest);
281
```
282

283
## Matching Strategies
284

285
The API Definition System supports three URL matching strategies through `SentinelGatewayConstants`:
286

287
- **EXACT (0)**: Exact string match
288
- **PREFIX (1)**: Prefix-based matching (most common for API groups)
289
- **REGEX (2)**: Regular expression matching for complex patterns
290

291
## Best Practices
292

293
1. **Use descriptive API names** that clearly identify the service or functionality
294
2. **Group related endpoints** under the same API definition using prefix matching
295
3. **Validate API definitions** using `isValidApi()` before loading
296
4. **Use regex matching sparingly** as it has performance implications
297
5. **Implement observers** for dynamic API definition updates in production systems