0
# API and Resources
1
2
Core classes for creating RESTful APIs with automatic documentation, routing, and response handling. The Api class serves as the main entry point for Flask-RESTPlus applications, while Resource provides the base class for defining API endpoints.
3
4
## Capabilities
5
6
### Api Class
7
8
The main class that wraps a Flask application to provide RESTful API functionality with automatic documentation generation.
9
10
```python { .api }
11
class Api:
12
def __init__(self, app=None, version='1.0', title=None, description=None,
13
terms_url=None, license=None, license_url=None, contact=None,
14
contact_url=None, contact_email=None, authorizations=None,
15
security=None, doc='/', default_id=None, default='default',
16
validate=None, tags=None, prefix='', ordered=False, **kwargs):
17
"""
18
Initialize the API.
19
20
Args:
21
app (Flask, optional): Flask application instance
22
version (str): API version
23
title (str, optional): API title
24
description (str, optional): API description
25
terms_url (str, optional): Terms of service URL
26
license (str, optional): License name
27
license_url (str, optional): License URL
28
contact (str, optional): Contact name
29
contact_url (str, optional): Contact URL
30
contact_email (str, optional): Contact email
31
authorizations (dict, optional): Authorization definitions
32
security (list, optional): Global security requirements
33
doc (str): Documentation endpoint path
34
default_id (callable, optional): Default operation ID generator
35
default (str): Default namespace name
36
validate (bool, optional): Enable request validation
37
tags (list, optional): Global tags
38
prefix (str): URL prefix for all routes
39
ordered (bool): Preserve model field ordering
40
"""
41
42
def init_app(self, app, **kwargs):
43
"""
44
Initialize the API with a Flask app.
45
46
Args:
47
app (Flask): Flask application instance
48
**kwargs: Additional configuration options
49
"""
50
51
def add_resource(self, resource, *urls, endpoint=None, **kwargs):
52
"""
53
Add a resource to the API.
54
55
Args:
56
resource (Resource): Resource class to add
57
*urls (str): URL routes for the resource
58
endpoint (str, optional): Endpoint name
59
**kwargs: Additional route arguments
60
61
Returns:
62
Resource: The added resource class
63
"""
64
65
def route(self, *urls, **kwargs):
66
"""
67
Decorator to add a resource route.
68
69
Args:
70
*urls (str): URL routes
71
**kwargs: Route arguments
72
73
Returns:
74
callable: Decorator function
75
"""
76
77
def add_namespace(self, ns, path=None):
78
"""
79
Add a namespace to the API.
80
81
Args:
82
ns (Namespace): Namespace to add
83
path (str, optional): URL path prefix
84
"""
85
86
def namespace(self, *args, **kwargs):
87
"""
88
Create and return a new namespace.
89
90
Args:
91
*args: Namespace arguments
92
**kwargs: Namespace keyword arguments
93
94
Returns:
95
Namespace: New namespace instance
96
"""
97
98
def model(self, name=None, model=None, mask=None, strict=False, **kwargs):
99
"""
100
Register a model for documentation and validation.
101
102
Args:
103
name (str, optional): Model name
104
model (dict or Model, optional): Model definition
105
mask (str, optional): Field mask
106
strict (bool): Strict validation mode
107
**kwargs: Model fields
108
109
Returns:
110
Model: Registered model
111
"""
112
113
def clone(self, name, model, **kwargs):
114
"""
115
Clone an existing model with modifications.
116
117
Args:
118
name (str): New model name
119
model (Model): Model to clone
120
**kwargs: Field modifications
121
122
Returns:
123
Model: Cloned model
124
"""
125
126
def inherit(self, name, *parents, **kwargs):
127
"""
128
Create a model inheriting from parent models.
129
130
Args:
131
name (str): New model name
132
*parents (Model): Parent models
133
**kwargs: Additional fields
134
135
Returns:
136
Model: Inherited model
137
"""
138
139
def expect(*inputs, validate=None):
140
"""
141
Decorator for documenting expected request inputs.
142
143
Args:
144
*inputs: Expected input models or parsers
145
validate (bool, optional): Enable validation
146
147
Returns:
148
callable: Decorator function
149
"""
150
151
def marshal_with(fields, as_list=False, code=200, description=None, **kwargs):
152
"""
153
Decorator for marshalling response data.
154
155
Args:
156
fields (dict or Model): Fields for marshalling
157
as_list (bool): Marshal as list
158
code (int): HTTP status code
159
description (str, optional): Response description
160
**kwargs: Additional marshal options
161
162
Returns:
163
callable: Decorator function
164
"""
165
166
def marshal_list_with(fields, **kwargs):
167
"""
168
Decorator for marshalling list responses.
169
170
Args:
171
fields (dict or Model): Fields for marshalling
172
**kwargs: Additional marshal options
173
174
Returns:
175
callable: Decorator function
176
"""
177
178
def doc(self, shortcut=None, **kwargs):
179
"""
180
Decorator for adding documentation to resources.
181
182
Args:
183
shortcut (str, optional): Documentation shortcut
184
**kwargs: Documentation parameters
185
186
Returns:
187
callable: Decorator function
188
"""
189
190
def hide(self):
191
"""
192
Decorator to hide a resource from documentation.
193
194
Returns:
195
callable: Decorator function
196
"""
197
198
def deprecated(self):
199
"""
200
Decorator to mark a resource as deprecated.
201
202
Returns:
203
callable: Decorator function
204
"""
205
206
def header(self, name, description=None, **kwargs):
207
"""
208
Decorator for documenting expected headers.
209
210
Args:
211
name (str): Header name
212
description (str, optional): Header description
213
**kwargs: Additional header parameters
214
215
Returns:
216
callable: Decorator function
217
"""
218
219
def produces(self, mimetypes):
220
"""
221
Decorator for documenting response content types.
222
223
Args:
224
mimetypes (list): Supported MIME types
225
226
Returns:
227
callable: Decorator function
228
"""
229
230
def response(self, code, description, model=None, **kwargs):
231
"""
232
Decorator for documenting response schemas.
233
234
Args:
235
code (int): HTTP status code
236
description (str): Response description
237
model (Model, optional): Response model
238
**kwargs: Additional response parameters
239
240
Returns:
241
callable: Decorator function
242
"""
243
244
def errorhandler(self, exception):
245
"""
246
Register an error handler.
247
248
Args:
249
exception (Exception): Exception class
250
251
Returns:
252
callable: Decorator function
253
"""
254
255
def owns_endpoint(self, endpoint):
256
"""
257
Check if API owns an endpoint.
258
259
Args:
260
endpoint (str): Endpoint name
261
262
Returns:
263
bool: True if owned by this API
264
"""
265
266
def output(self, resource):
267
"""
268
Apply output formatting to a resource response.
269
270
Args:
271
resource: Resource response
272
273
Returns:
274
Response: Formatted response
275
"""
276
277
@property
278
def payload(self):
279
"""
280
Get the current request payload.
281
282
Returns:
283
dict: Request payload data
284
"""
285
286
@property
287
def specs_url(self):
288
"""
289
Get the Swagger specification URL.
290
291
Returns:
292
str: Swagger JSON URL
293
"""
294
295
def add_resource(self, resource, *urls, **kwargs):
296
"""
297
Add a resource to the API.
298
299
Args:
300
resource: Resource class to add
301
*urls: URL patterns for the resource
302
**kwargs: Additional resource options
303
"""
304
305
def make_response(self, data, *args, **kwargs):
306
"""
307
Create a Flask response from data.
308
309
Args:
310
data: Response data
311
*args: Additional arguments
312
**kwargs: Additional keyword arguments
313
314
Returns:
315
Response: Flask response object
316
"""
317
318
def error_router(self, original_handler, e):
319
"""
320
Route errors to appropriate handlers.
321
322
Args:
323
original_handler: Original error handler
324
e (Exception): Exception to handle
325
326
Returns:
327
Response: Error response
328
"""
329
330
def handle_error(self, e):
331
"""
332
Handle API errors.
333
334
Args:
335
e (Exception): Exception to handle
336
337
Returns:
338
Response: Error response
339
"""
340
341
def as_postman(self, urlvars=False, swagger=False):
342
"""
343
Generate Postman collection for the API.
344
345
Args:
346
urlvars (bool): Include URL variables
347
swagger (bool): Use Swagger definitions
348
349
Returns:
350
dict: Postman collection data
351
"""
352
```
353
354
### Resource Class
355
356
Base class for API resources that handles HTTP method routing and provides integration with Flask-RESTPlus features.
357
358
```python { .api }
359
class Resource:
360
# Class attributes
361
representations = None # Custom response representations
362
method_decorators = [] # Decorators applied to all methods
363
364
def __init__(self, api=None, *args, **kwargs):
365
"""
366
Initialize the resource.
367
368
Args:
369
api (Api, optional): Associated API instance
370
*args: Additional arguments
371
**kwargs: Additional keyword arguments
372
"""
373
374
def dispatch_request(self, *args, **kwargs):
375
"""
376
Dispatch the request to the appropriate HTTP method handler.
377
378
Args:
379
*args: URL route arguments
380
**kwargs: URL route keyword arguments
381
382
Returns:
383
Response: HTTP response
384
"""
385
386
def validate_payload(self, func):
387
"""
388
Validate request payload against expected model.
389
390
Args:
391
func (callable): Handler function to validate for
392
"""
393
394
# HTTP method handlers (implement as needed)
395
def get(self, *args, **kwargs):
396
"""Handle GET requests."""
397
398
def post(self, *args, **kwargs):
399
"""Handle POST requests."""
400
401
def put(self, *args, **kwargs):
402
"""Handle PUT requests."""
403
404
def patch(self, *args, **kwargs):
405
"""Handle PATCH requests."""
406
407
def delete(self, *args, **kwargs):
408
"""Handle DELETE requests."""
409
410
def head(self, *args, **kwargs):
411
"""Handle HEAD requests."""
412
413
def options(self, *args, **kwargs):
414
"""Handle OPTIONS requests."""
415
```
416
417
### Namespace Class
418
419
Groups related resources together with shared configuration, similar to Flask Blueprints but with additional API documentation features.
420
421
```python { .api }
422
class Namespace:
423
def __init__(self, name, description=None, path=None, decorators=None,
424
validate=None, authorizations=None, ordered=False, **kwargs):
425
"""
426
Initialize the namespace.
427
428
Args:
429
name (str): Namespace name
430
description (str, optional): Namespace description
431
path (str, optional): URL path prefix
432
decorators (list, optional): Decorators to apply to all resources
433
validate (bool, optional): Enable request validation
434
authorizations (dict, optional): Authorization definitions
435
ordered (bool): Preserve field ordering in models
436
**kwargs: Additional namespace options
437
"""
438
439
def add_resource(self, resource, *urls, **kwargs):
440
"""
441
Add a resource to this namespace.
442
443
Args:
444
resource (Resource): Resource class to add
445
*urls (str): URL routes for the resource
446
**kwargs: Additional route arguments
447
"""
448
449
def route(self, *urls, **kwargs):
450
"""
451
Decorator to add a resource route to this namespace.
452
453
Args:
454
*urls (str): URL routes
455
**kwargs: Route arguments
456
457
Returns:
458
callable: Decorator function
459
"""
460
461
def model(self, name=None, model=None, **kwargs):
462
"""
463
Register a model in this namespace.
464
465
Args:
466
name (str, optional): Model name
467
model (dict or Model, optional): Model definition
468
**kwargs: Model fields
469
470
Returns:
471
Model: Registered model
472
"""
473
474
def clone(self, name, model, **kwargs):
475
"""
476
Clone an existing model in this namespace.
477
478
Args:
479
name (str): New model name
480
model (Model): Model to clone
481
**kwargs: Field modifications
482
483
Returns:
484
Model: Cloned model
485
"""
486
487
def inherit(self, name, *parents, **kwargs):
488
"""
489
Create an inherited model in this namespace.
490
491
Args:
492
name (str): New model name
493
*parents (Model): Parent models
494
**kwargs: Additional fields
495
496
Returns:
497
Model: Inherited model
498
"""
499
500
def expect(*inputs, validate=None):
501
"""
502
Namespace-specific expect decorator.
503
504
Args:
505
*inputs: Expected input models or parsers
506
validate (bool, optional): Enable validation
507
508
Returns:
509
callable: Decorator function
510
"""
511
512
def marshal_with(fields, **kwargs):
513
"""
514
Namespace-specific marshal_with decorator.
515
516
Args:
517
fields (dict or Model): Fields for marshalling
518
**kwargs: Marshal options
519
520
Returns:
521
callable: Decorator function
522
"""
523
524
def marshal_list_with(fields, **kwargs):
525
"""
526
Namespace-specific marshal_list_with decorator.
527
528
Args:
529
fields (dict or Model): Fields for marshalling
530
**kwargs: Marshal options
531
532
Returns:
533
callable: Decorator function
534
"""
535
536
def doc(self, shortcut=None, **kwargs):
537
"""
538
Namespace-specific documentation decorator.
539
540
Args:
541
shortcut (str, optional): Documentation shortcut
542
**kwargs: Documentation parameters
543
544
Returns:
545
callable: Decorator function
546
"""
547
548
def hide(self):
549
"""
550
Decorator to hide resources from documentation.
551
552
Returns:
553
callable: Decorator function
554
"""
555
556
def deprecated(self):
557
"""
558
Decorator to mark resources as deprecated.
559
560
Returns:
561
callable: Decorator function
562
"""
563
564
def header(self, name, description=None, **kwargs):
565
"""
566
Namespace-specific header documentation decorator.
567
568
Args:
569
name (str): Header name
570
description (str, optional): Header description
571
**kwargs: Additional header parameters
572
573
Returns:
574
callable: Decorator function
575
"""
576
577
def produces(self, mimetypes):
578
"""
579
Namespace-specific produces decorator.
580
581
Args:
582
mimetypes (list): Supported MIME types
583
584
Returns:
585
callable: Decorator function
586
"""
587
588
def response(self, code, description, model=None, **kwargs):
589
"""
590
Namespace-specific response documentation decorator.
591
592
Args:
593
code (int): HTTP status code
594
description (str): Response description
595
model (Model, optional): Response model
596
**kwargs: Additional response parameters
597
598
Returns:
599
callable: Decorator function
600
"""
601
602
def errorhandler(self, exception):
603
"""
604
Register a namespace-specific error handler.
605
606
Args:
607
exception (Exception): Exception class
608
609
Returns:
610
callable: Decorator function
611
"""
612
613
def param(self, name, description=None, **kwargs):
614
"""
615
Decorator for documenting URL parameters.
616
617
Args:
618
name (str): Parameter name
619
description (str, optional): Parameter description
620
**kwargs: Additional parameter options
621
622
Returns:
623
callable: Decorator function
624
"""
625
626
@property
627
def path(self):
628
"""
629
Get the namespace URL path.
630
631
Returns:
632
str: URL path prefix
633
"""
634
635
@property
636
def payload(self):
637
"""
638
Get the current request payload for this namespace.
639
640
Returns:
641
dict: Request payload data
642
"""
643
```
644
645
## Usage Examples
646
647
### Basic API Setup
648
649
```python
650
from flask import Flask
651
from flask_restplus import Api, Resource
652
653
app = Flask(__name__)
654
api = Api(
655
app,
656
version='1.0',
657
title='My API',
658
description='A simple demonstration API',
659
doc='/doc/'
660
)
661
662
@api.route('/hello')
663
class HelloWorld(Resource):
664
def get(self):
665
return {'message': 'Hello, World!'}
666
667
if __name__ == '__main__':
668
app.run(debug=True)
669
```
670
671
### Using Namespaces
672
673
```python
674
from flask import Flask
675
from flask_restplus import Api, Resource, Namespace
676
677
app = Flask(__name__)
678
api = Api(app, doc='/doc/')
679
680
# Create namespaces
681
users_ns = api.namespace('users', description='User operations')
682
posts_ns = api.namespace('posts', description='Post operations')
683
684
@users_ns.route('/')
685
class UserList(Resource):
686
def get(self):
687
return [{'id': 1, 'name': 'John Doe'}]
688
689
@posts_ns.route('/')
690
class PostList(Resource):
691
def get(self):
692
return [{'id': 1, 'title': 'First Post', 'author_id': 1}]
693
```
694
695
### Advanced API Configuration
696
697
```python
698
from flask import Flask
699
from flask_restplus import Api
700
701
app = Flask(__name__)
702
703
# Advanced API configuration
704
api = Api(
705
app,
706
version='2.0',
707
title='Advanced API',
708
description='An API with advanced configuration',
709
terms_url='http://example.com/terms',
710
license='MIT',
711
license_url='http://opensource.org/licenses/MIT',
712
contact='API Support',
713
contact_email='support@example.com',
714
doc='/documentation/',
715
validate=True, # Enable request validation
716
ordered=True, # Preserve field ordering
717
prefix='/api/v2' # URL prefix for all routes
718
)
719
```