0
# REST API Specifications
1

2
Type-safe REST API definitions including headers, parameters, and message specifications. These classes provide compile-time safety for API contracts and ensure consistent endpoint behavior across the Flink web interface.
3

4
## Capabilities
5

6
### JAR Upload API Specification
7

8
Defines the REST API contract for JAR file uploads.
9

10
```java { .api }
11
/**
12
 * REST API specification for JAR file upload endpoint.
13
 * Defines the contract for POST /jars/upload operations.
14
 */
15
public class JarUploadHeaders implements MessageHeaders<EmptyRequestBody, JarUploadResponseBody, EmptyMessageParameters> {
16
    /**
17
     * Get the singleton instance of JAR upload headers.
18
     * 
19
     * @return The JAR upload headers instance
20
     */
21
    public static JarUploadHeaders getInstance();
22
    
23
    /**
24
     * Get the HTTP method for this endpoint.
25
     * 
26
     * @return HttpMethodWrapper.POST
27
     */
28
    public HttpMethodWrapper getHttpMethod();
29
    
30
    /**
31
     * Get the URL pattern for this endpoint.
32
     * 
33
     * @return "/jars/upload"
34
     */
35
    public String getTargetRestEndpointURL();
36
    
37
    /**
38
     * Get the request body class.
39
     * 
40
     * @return EmptyRequestBody.class
41
     */
42
    public Class<EmptyRequestBody> getRequestClass();
43
    
44
    /**
45
     * Get the response body class.
46
     * 
47
     * @return JarUploadResponseBody.class
48
     */
49
    public Class<JarUploadResponseBody> getResponseClass();
50
    
51
    /**
52
     * Get the message parameters class.
53
     * 
54
     * @return EmptyMessageParameters.class
55
     */
56
    public Class<EmptyMessageParameters> getUnresolvedMessageParameters();
57
}
58
```
59

60
### JAR Run API Specification
61

62
Defines the REST API contract for JAR execution.
63

64
```java { .api }
65
/**
66
 * REST API specification for JAR execution endpoint.
67
 * Defines the contract for POST /jars/:jarId/run operations.
68
 */
69
public class JarRunHeaders implements MessageHeaders<JarRunRequestBody, JarRunResponseBody, JarRunMessageParameters> {
70
    /**
71
     * Get the singleton instance of JAR run headers.
72
     * 
73
     * @return The JAR run headers instance
74
     */
75
    public static JarRunHeaders getInstance();
76
    
77
    /**
78
     * Get the HTTP method for this endpoint.
79
     * 
80
     * @return HttpMethodWrapper.POST
81
     */
82
    public HttpMethodWrapper getHttpMethod();
83
    
84
    /**
85
     * Get the URL pattern for this endpoint.
86
     * 
87
     * @return "/jars/:jarId/run"
88
     */
89
    public String getTargetRestEndpointURL();
90
    
91
    /**
92
     * Get the request body class.
93
     * 
94
     * @return JarRunRequestBody.class
95
     */
96
    public Class<JarRunRequestBody> getRequestClass();
97
    
98
    /**
99
     * Get the response body class.
100
     * 
101
     * @return JarRunResponseBody.class
102
     */
103
    public Class<JarRunResponseBody> getResponseClass();
104
    
105
    /**
106
     * Get the message parameters class.
107
     * 
108
     * @return JarRunMessageParameters.class
109
     */
110
    public Class<JarRunMessageParameters> getUnresolvedMessageParameters();
111
}
112
```
113

114
### JAR List API Specification
115

116
Defines the REST API contract for listing uploaded JARs.
117

118
```java { .api }
119
/**
120
 * REST API specification for JAR listing endpoint.
121
 * Defines the contract for GET /jars operations.
122
 */
123
public class JarListHeaders implements MessageHeaders<EmptyRequestBody, JarListInfo, EmptyMessageParameters> {
124
    /**
125
     * Get the singleton instance of JAR list headers.
126
     * 
127
     * @return The JAR list headers instance
128
     */
129
    public static JarListHeaders getInstance();
130
    
131
    /**
132
     * Get the HTTP method for this endpoint.
133
     * 
134
     * @return HttpMethodWrapper.GET
135
     */
136
    public HttpMethodWrapper getHttpMethod();
137
    
138
    /**
139
     * Get the URL pattern for this endpoint.
140
     * 
141
     * @return "/jars"
142
     */
143
    public String getTargetRestEndpointURL();
144
}
145
```
146

147
### JAR Delete API Specification
148

149
Defines the REST API contract for JAR deletion.
150

151
```java { .api }
152
/**
153
 * REST API specification for JAR deletion endpoint.
154
 * Defines the contract for DELETE /jars/:jarId operations.
155
 */
156
public class JarDeleteHeaders implements MessageHeaders<EmptyRequestBody, EmptyResponseBody, JarDeleteMessageParameters> {
157
    /**
158
     * Get the singleton instance of JAR delete headers.
159
     * 
160
     * @return The JAR delete headers instance
161
     */
162
    public static JarDeleteHeaders getInstance();
163
    
164
    /**
165
     * Get the HTTP method for this endpoint.
166
     * 
167
     * @return HttpMethodWrapper.DELETE
168
     */
169
    public HttpMethodWrapper getHttpMethod();
170
    
171
    /**
172
     * Get the URL pattern for this endpoint.
173
     * 
174
     * @return "/jars/:jarId"
175
     */
176
    public String getTargetRestEndpointURL();
177
}
178
```
179

180
### JAR Plan API Specifications
181

182
Defines the REST API contracts for execution plan generation.
183

184
```java { .api }
185
/**
186
 * REST API specification for JAR plan retrieval via GET.
187
 * Defines the contract for GET /jars/:jarId/plan operations.
188
 */
189
public class JarPlanGetHeaders implements MessageHeaders<EmptyRequestBody, JobPlanInfo, JarPlanMessageParameters> {
190
    public static JarPlanGetHeaders getInstance();
191
    public HttpMethodWrapper getHttpMethod(); // GET
192
    public String getTargetRestEndpointURL(); // "/jars/:jarId/plan"
193
}
194

195
/**
196
 * REST API specification for JAR plan generation via POST.
197
 * Defines the contract for POST /jars/:jarId/plan operations with request body.
198
 */
199
public class JarPlanPostHeaders implements MessageHeaders<JarPlanRequestBody, JobPlanInfo, JarPlanMessageParameters> {
200
    public static JarPlanPostHeaders getInstance();
201
    public HttpMethodWrapper getHttpMethod(); // POST
202
    public String getTargetRestEndpointURL(); // "/jars/:jarId/plan"
203
}
204

205
/**
206
 * Abstract base class for JAR plan API specifications.
207
 * Provides common functionality for both GET and POST plan endpoints.
208
 */
209
public abstract class AbstractJarPlanHeaders implements MessageHeaders {
210
    /**
211
     * Get the description of this endpoint.
212
     * 
213
     * @return Description string for the plan endpoint
214
     */
215
    public String getDescription();
216
}
217
```
218

219
## Path Parameters
220

221
### JAR ID Path Parameter
222

223
Type-safe path parameter for JAR identification in URLs.
224

225
```java { .api }
226
/**
227
 * Path parameter for JAR file identification in REST URLs.
228
 * Used in endpoints like /jars/:jarId/run, /jars/:jarId/plan, etc.
229
 */
230
public class JarIdPathParameter extends MessagePathParameter<String> {
231
    /**
232
     * Get the parameter key used in URL templates.
233
     * 
234
     * @return "jarId"
235
     */
236
    public String getKey();
237
    
238
    /**
239
     * Convert path value to typed parameter.
240
     * 
241
     * @param value String value from URL path
242
     * @return The JAR ID as a string
243
     */
244
    public String convertFromString(String value);
245
    
246
    /**
247
     * Convert typed parameter to path value.
248
     * 
249
     * @param object The JAR ID object
250
     * @return String representation for URL path
251
     */
252
    public String convertToString(String object);
253
    
254
    /**
255
     * Get the description of this parameter.
256
     * 
257
     * @return Description of the JAR ID parameter
258
     */
259
    public String getDescription();
260
}
261
```
262

263
## Query Parameters
264

265
### Entry Class Query Parameter
266

267
Query parameter for specifying the main class of a JAR file.
268

269
```java { .api }
270
/**
271
 * Query parameter for specifying the entry class (main class) of a JAR file.
272
 * Used in JAR execution and plan generation endpoints.
273
 */
274
public class EntryClassQueryParameter extends MessageQueryParameter<String> {
275
    /**
276
     * Get the parameter key used in query strings.
277
     * 
278
     * @return "entry-class"
279
     */
280
    public String getKey();
281
    
282
    /**
283
     * Convert query value to typed parameter.
284
     * 
285
     * @param value String value from query string
286
     * @return The entry class name
287
     */
288
    public String convertFromString(String value);
289
    
290
    /**
291
     * Get the description of this parameter.
292
     * 
293
     * @return Description of the entry class parameter
294
     */
295
    public String getDescription();
296
    
297
    /**
298
     * Check if this parameter is mandatory.
299
     * 
300
     * @return false (entry class is optional)
301
     */
302
    public boolean isMandatory();
303
}
304
```
305

306
### Parallelism Query Parameter
307

308
Query parameter for specifying job parallelism.
309

310
```java { .api }
311
/**
312
 * Query parameter for specifying the parallelism of a Flink job.
313
 * Used in JAR execution endpoints to override default parallelism.
314
 */
315
public class ParallelismQueryParameter extends MessageQueryParameter<Integer> {
316
    /**
317
     * Get the parameter key used in query strings.
318
     * 
319
     * @return "parallelism"
320
     */
321
    public String getKey();
322
    
323
    /**
324
     * Convert query value to typed parameter.
325
     * 
326
     * @param value String value from query string
327
     * @return The parallelism as an integer
328
     */
329
    public Integer convertFromString(String value);
330
    
331
    /**
332
     * Get the description of this parameter.
333
     * 
334
     * @return Description of the parallelism parameter
335
     */
336
    public String getDescription();
337
    
338
    /**
339
     * Check if this parameter is mandatory.
340
     * 
341
     * @return false (parallelism is optional)
342
     */
343
    public boolean isMandatory();
344
}
345
```
346

347
### Program Arguments Query Parameters
348

349
Query parameters for passing arguments to JAR programs.
350

351
```java { .api }
352
/**
353
 * Query parameter for passing individual program arguments to JAR execution.
354
 * Can be specified multiple times to pass multiple arguments.
355
 */
356
public class ProgramArgQueryParameter extends MessageQueryParameter<String> {
357
    public String getKey(); // "program-arg"
358
    public String convertFromString(String value);
359
    public String getDescription();
360
    public boolean isMandatory(); // false
361
}
362

363
/**
364
 * Query parameter for passing all program arguments as a single string.
365
 * Arguments are tokenized and passed to the program.
366
 */
367
public class ProgramArgsQueryParameter extends MessageQueryParameter<String> {
368
    public String getKey(); // "program-args"
369
    public String convertFromString(String value);
370
    public String getDescription();
371
    public boolean isMandatory(); // false
372
}
373
```
374

375
### Savepoint Query Parameters
376

377
Query parameters for savepoint-related operations.
378

379
```java { .api }
380
/**
381
 * Query parameter for specifying savepoint path for job restoration.
382
 * Used when starting jobs from a specific savepoint.
383
 */
384
public class SavepointPathQueryParameter extends MessageQueryParameter<String> {
385
    public String getKey(); // "savepointPath"
386
    public String convertFromString(String value);
387
    public String getDescription();
388
    public boolean isMandatory(); // false
389
}
390

391
/**
392
 * Query parameter for allowing non-restored state when restoring from savepoint.
393
 * Controls whether jobs can start even if some state cannot be restored.
394
 */
395
public class AllowNonRestoredStateQueryParameter extends MessageQueryParameter<Boolean> {
396
    public String getKey(); // "allowNonRestoredState"
397
    public Boolean convertFromString(String value);
398
    public String getDescription();
399
    public boolean isMandatory(); // false
400
}
401
```
402

403
### Base Query Parameter Class
404

405
Base class for all string-based query parameters.
406

407
```java { .api }
408
/**
409
 * Base class for string-based query parameters.
410
 * Provides common functionality for string parameter handling.
411
 */
412
public class StringQueryParameter extends MessageQueryParameter<String> {
413
    /**
414
     * Create a string query parameter.
415
     * 
416
     * @param key The parameter key
417
     * @param description Description of the parameter
418
     */
419
    public StringQueryParameter(String key, String description);
420
    
421
    /**
422
     * Convert query value to string (identity conversion).
423
     * 
424
     * @param value String value from query string
425
     * @return The same string value
426
     */
427
    public String convertFromString(String value);
428
    
429
    /**
430
     * Check if this parameter is mandatory.
431
     * 
432
     * @return false (optional by default)
433
     */
434
    public boolean isMandatory();
435
}
436
```
437

438
## Message Parameters
439

440
### JAR Message Parameters
441

442
Base message parameters for JAR operations.
443

444
```java { .api }
445
/**
446
 * Base message parameters for JAR-related operations.
447
 * Provides common parameter handling for JAR endpoints.
448
 */
449
public class JarMessageParameters extends MessageParameters {
450
    /**
451
     * Get the JAR ID path parameter.
452
     * 
453
     * @return JarIdPathParameter instance
454
     */
455
    public JarIdPathParameter getJarIdPathParameter();
456
    
457
    /**
458
     * Get all path parameters for this message.
459
     * 
460
     * @return Collection of path parameters
461
     */
462
    public Collection<MessagePathParameter<?>> getPathParameters();
463
    
464
    /**
465
     * Get all query parameters for this message.
466
     * 
467
     * @return Collection of query parameters
468
     */
469
    public Collection<MessageQueryParameter<?>> getQueryParameters();
470
}
471
```
472

473
### Specific Message Parameters
474

475
Specialized message parameters for different JAR operations.
476

477
```java { .api }
478
/**
479
 * Message parameters for JAR deletion operations.
480
 * Includes only the JAR ID path parameter.
481
 */
482
public class JarDeleteMessageParameters extends JarMessageParameters {
483
    // Inherits JAR ID path parameter
484
}
485

486
/**
487
 * Message parameters for JAR execution operations.
488
 * Includes JAR ID and optional query parameters for job configuration.
489
 */
490
public class JarRunMessageParameters extends JarMessageParameters {
491
    // Includes parallelism, entry class, program args, savepoint parameters
492
}
493

494
/**
495
 * Message parameters for JAR plan operations.
496
 * Includes JAR ID and optional query parameters for plan generation.
497
 */
498
public class JarPlanMessageParameters extends JarMessageParameters {
499
    // Includes entry class and program args parameters
500
}
501
```
502

503
## Usage Examples
504

505
### Creating Type-Safe REST Handlers
506

507
```java
508
import org.apache.flink.runtime.webmonitor.handlers.*;
509

510
// Use headers to create type-safe handlers
511
JarUploadHeaders uploadHeaders = JarUploadHeaders.getInstance();
512
JarRunHeaders runHeaders = JarRunHeaders.getInstance(); 
513
JarListHeaders listHeaders = JarListHeaders.getInstance();
514

515
// Headers provide compile-time type safety
516
Class<JarRunRequestBody> requestType = runHeaders.getRequestClass();
517
Class<JarRunResponseBody> responseType = runHeaders.getResponseClass();
518
String endpoint = runHeaders.getTargetRestEndpointURL(); // "/jars/:jarId/run"
519
```
520

521
### Parameter Extraction and Validation
522

523
```java
524
// Extract and validate parameters from requests
525
JarRunMessageParameters messageParams = new JarRunMessageParameters();
526
Collection<MessagePathParameter<?>> pathParams = messageParams.getPathParameters();
527
Collection<MessageQueryParameter<?>> queryParams = messageParams.getQueryParameters();
528

529
// Type-safe parameter access
530
JarIdPathParameter jarIdParam = messageParams.getJarIdPathParameter();
531
String jarId = jarIdParam.convertFromString(pathValue);
532

533
// Query parameter validation
534
ParallelismQueryParameter parallelismParam = new ParallelismQueryParameter();
535
if (!parallelismParam.isMandatory() && queryString.contains("parallelism")) {
536
    Integer parallelism = parallelismParam.convertFromString(queryValue);
537
}
538
```
539

540
This type-safe parameter system ensures API consistency and prevents runtime errors through compile-time validation of endpoint contracts.