Mercurial > hg > nginx-site
comparison yaml/nginx_api.yaml @ 2082:fee7627f6a5a
Updated docs for the upcoming NGINX Plus release.
author | Ruslan Ermilov <ru@nginx.com> |
---|---|
date | Mon, 11 Dec 2017 12:13:09 +0300 |
parents | 116994597b0e |
children | a645aa9f2ebf |
comparison
equal
deleted
inserted
replaced
2081:f29bd40e9a62 | 2082:fee7627f6a5a |
---|---|
1 swagger: '2.0' | 1 swagger: '2.0' |
2 info: | 2 info: |
3 version: '1.0' | 3 version: '2.0' |
4 title: NGINX Plus REST API | 4 title: NGINX Plus REST API |
5 description: NGINX Plus REST | 5 description: NGINX Plus REST |
6 [API](https://nginx.org/en/docs/http/ngx_http_api_module.html) | 6 [API](https://nginx.org/en/docs/http/ngx_http_api_module.html) |
7 provides access to NGINX Plus status information, | 7 provides access to NGINX Plus status information, |
8 on-the-fly configuration of upstream servers and | 8 on-the-fly configuration of upstream servers and |
9 [key-value](https://nginx.org/en/docs/http/ngx_http_keyval_module.html) | 9 key-value pairs management for |
10 pairs management. | 10 [http](https://nginx.org/en/docs/http/ngx_http_keyval_module.html) and |
11 basePath: /api/1 | 11 [stream](https://nginx.org/en/docs/stream/ngx_stream_keyval_module.html). |
12 basePath: /api/2 | |
12 tags: | 13 tags: |
13 - name: General Info | 14 - name: General Info |
14 - name: Processes | 15 - name: Processes |
15 - name: Connections | 16 - name: Connections |
16 - name: SSL | 17 - name: SSL |
22 - name: HTTP Upstreams | 23 - name: HTTP Upstreams |
23 - name: HTTP Keyvals | 24 - name: HTTP Keyvals |
24 - name: Stream | 25 - name: Stream |
25 - name: Stream Server Zones | 26 - name: Stream Server Zones |
26 - name: Stream Upstreams | 27 - name: Stream Upstreams |
28 - name: Stream Keyvals | |
27 - name: Method GET | 29 - name: Method GET |
28 - name: Method POST | 30 - name: Method POST |
29 - name: Method PATCH | 31 - name: Method PATCH |
30 - name: Method DELETE | 32 - name: Method DELETE |
31 schemes: | 33 schemes: |
727 /http/keyvals/: | 729 /http/keyvals/: |
728 get: | 730 get: |
729 tags: | 731 tags: |
730 - HTTP Keyvals | 732 - HTTP Keyvals |
731 - Method GET | 733 - Method GET |
732 summary: Return key-value pairs from all keyval zones | 734 summary: Return key-value pairs from all HTTP keyval zones |
733 description: Returns key-value pairs for each keyval shared memory | 735 description: Returns key-value pairs for each HTTP keyval shared memory |
734 [zone](https://nginx.org/en/docs/http/ngx_http_keyval_module.html#keyval_zone). | 736 [zone](https://nginx.org/en/docs/http/ngx_http_keyval_module.html#keyval_zone). |
735 operationId: getHttpKeyvalZones | 737 operationId: getHttpKeyvalZones |
736 produces: | 738 produces: |
737 - application/json | 739 - application/json |
738 parameters: | 740 parameters: |
739 - name: fields | 741 - name: fields |
740 in: query | 742 in: query |
741 type: string | 743 type: string |
742 description: If the “<literal>fields</literal>” value is empty, | 744 description: If the “<literal>fields</literal>” value is empty, |
743 then only keyval zone names are output. | 745 then only HTTP keyval zone names are output. |
744 responses: | 746 responses: |
745 '200': | 747 '200': |
746 description: Success | 748 description: Success |
747 schema: | 749 schema: |
748 $ref: '#/definitions/NginxHTTPKeyvalZonesMap' | 750 $ref: '#/definitions/NginxHTTPKeyvalZonesMap' |
749 '/http/keyvals/{httpKeyvalZoneName}': | 751 '/http/keyvals/{httpKeyvalZoneName}': |
750 parameters: | 752 parameters: |
751 - name: httpKeyvalZoneName | 753 - name: httpKeyvalZoneName |
752 in: path | 754 in: path |
753 description: The name of a keyval shared memory zone. | 755 description: The name of an HTTP keyval shared memory zone. |
754 required: true | 756 required: true |
755 type: string | 757 type: string |
756 get: | 758 get: |
757 tags: | 759 tags: |
758 - HTTP Keyvals | 760 - HTTP Keyvals |
759 - Method GET | 761 - Method GET |
760 summary: Return key-value pairs from a keyval zone | 762 summary: Return key-value pairs from an HTTP keyval zone |
761 description: Returns key-value pairs stored in a particular keyval shared memory | 763 description: Returns key-value pairs stored in a particular HTTP keyval shared memory |
762 [zone](https://nginx.org/en/docs/http/ngx_http_keyval_module.html#keyval_zone). | 764 [zone](https://nginx.org/en/docs/http/ngx_http_keyval_module.html#keyval_zone). |
763 operationId: getHttpKeyvalZoneKeysValues | 765 operationId: getHttpKeyvalZoneKeysValues |
764 produces: | 766 produces: |
765 - application/json | 767 - application/json |
766 parameters: | 768 parameters: |
767 - name: key | 769 - name: key |
768 in: query | 770 in: query |
769 type: string | 771 type: string |
770 description: Get a particular key-value pair from the keyval zone. | 772 description: Get a particular key-value pair from the HTTP keyval zone. |
771 responses: | 773 responses: |
772 '200': | 774 '200': |
773 description: Success | 775 description: Success |
774 schema: | 776 schema: |
775 $ref: '#/definitions/NginxHTTPKeyvalZone' | 777 $ref: '#/definitions/NginxHTTPKeyvalZone' |
781 $ref: '#/definitions/NginxError' | 783 $ref: '#/definitions/NginxError' |
782 post: | 784 post: |
783 tags: | 785 tags: |
784 - HTTP Keyvals | 786 - HTTP Keyvals |
785 - Method POST | 787 - Method POST |
786 summary: Add a key-value pair to the keyval zone | 788 summary: Add a key-value pair to the HTTP keyval zone |
787 description: Adds a new key-value pair to the keyval shared memory | 789 description: Adds a new key-value pair to the HTTP keyval shared memory |
788 [zone](https://nginx.org/en/docs/http/ngx_http_keyval_module.html#keyval_zone). | 790 [zone](https://nginx.org/en/docs/http/ngx_http_keyval_module.html#keyval_zone). |
789 Several key-value pairs can be entered | 791 Several key-value pairs can be entered |
790 if the keyval shared memory zone is empty. | 792 if the HTTP keyval shared memory zone is empty. |
791 operationId: postHttpKeyvalZoneData | 793 operationId: postHttpKeyvalZoneData |
792 produces: | 794 produces: |
793 - application/json | 795 - application/json |
794 parameters: | 796 parameters: |
795 - in: body | 797 - in: body |
796 name: Key-value | 798 name: Key-value |
797 description: A key-value pair is specified in the JSON format. | 799 description: A key-value pair is specified in the JSON format. |
798 Several key-value pairs can be entered | 800 Several key-value pairs can be entered |
799 if the keyval shared memory zone is empty. | 801 if the HTTP keyval shared memory zone is empty. |
800 required: true | 802 required: true |
801 schema: | 803 schema: |
802 $ref: '#/definitions/NginxHTTPKeyvalZone' | 804 $ref: '#/definitions/NginxHTTPKeyvalZone' |
803 responses: | 805 responses: |
804 '201': | 806 '201': |
869 $ref: '#/definitions/NginxError' | 871 $ref: '#/definitions/NginxError' |
870 delete: | 872 delete: |
871 tags: | 873 tags: |
872 - HTTP Keyvals | 874 - HTTP Keyvals |
873 - Method DELETE | 875 - Method DELETE |
874 summary: Empty the keyval zone | 876 summary: Empty the HTTP keyval zone |
875 description: Deletes all key-value pairs from the keyval shared memory | 877 description: Deletes all key-value pairs from the HTTP keyval shared memory |
876 [zone](https://nginx.org/en/docs/http/ngx_http_keyval_module.html#keyval_zone). | 878 [zone](https://nginx.org/en/docs/http/ngx_http_keyval_module.html#keyval_zone). |
877 operationId: deleteHttpKeyvalZoneData | 879 operationId: deleteHttpKeyvalZoneData |
878 responses: | 880 responses: |
879 '204': | 881 '204': |
880 description: Success | 882 description: Success |
1292 $ref: '#/definitions/NginxError' | 1294 $ref: '#/definitions/NginxError' |
1293 '404': | 1295 '404': |
1294 description: | | 1296 description: | |
1295 Upstream not found (*UpstreamNotFound*), | 1297 Upstream not found (*UpstreamNotFound*), |
1296 server with ID “**id**” does not exist (*UpstreamServerNotFound*), | 1298 server with ID “**id**” does not exist (*UpstreamServerNotFound*), |
1299 [stream](https://nginx.org/en/docs/stream/ngx_stream_core_module.html#stream) not configured (*StreamNotConfigured*) | |
1300 schema: | |
1301 $ref: '#/definitions/NginxError' | |
1302 '405': | |
1303 description: Method disabled (*MethodDisabled*) | |
1304 schema: | |
1305 $ref: '#/definitions/NginxError' | |
1306 /stream/keyvals/: | |
1307 get: | |
1308 tags: | |
1309 - Stream Keyvals | |
1310 - Method GET | |
1311 summary: Return key-value pairs from all stream keyval zones | |
1312 description: Returns key-value pairs for each stream keyval shared memory | |
1313 [zone](https://nginx.org/en/docs/stream/ngx_stream_keyval_module.html#keyval_zone). | |
1314 operationId: getStreamKeyvalZones | |
1315 produces: | |
1316 - application/json | |
1317 parameters: | |
1318 - name: fields | |
1319 in: query | |
1320 type: string | |
1321 description: If the “<literal>fields</literal>” value is empty, | |
1322 then only stream keyval zone names are output. | |
1323 responses: | |
1324 '200': | |
1325 description: Success | |
1326 schema: | |
1327 $ref: '#/definitions/NginxStreamKeyvalZonesMap' | |
1328 '404': | |
1329 description: | | |
1330 [stream](https://nginx.org/en/docs/stream/ngx_stream_core_module.html#stream) not configured (*StreamNotConfigured*) | |
1331 schema: | |
1332 $ref: '#/definitions/NginxError' | |
1333 '/stream/keyvals/{streamKeyvalZoneName}': | |
1334 parameters: | |
1335 - name: streamKeyvalZoneName | |
1336 in: path | |
1337 description: The name of a stream keyval shared memory zone. | |
1338 required: true | |
1339 type: string | |
1340 get: | |
1341 tags: | |
1342 - Stream Keyvals | |
1343 - Method GET | |
1344 summary: Return key-value pairs from a stream keyval zone | |
1345 description: Returns key-value pairs stored in a particular stream keyval shared memory | |
1346 [zone](https://nginx.org/en/docs/stream/ngx_stream_keyval_module.html#keyval_zone). | |
1347 operationId: getStreamKeyvalZoneKeysValues | |
1348 produces: | |
1349 - application/json | |
1350 parameters: | |
1351 - name: key | |
1352 in: query | |
1353 type: string | |
1354 description: Get a particular key-value pair from the stream keyval zone. | |
1355 responses: | |
1356 '200': | |
1357 description: Success | |
1358 schema: | |
1359 $ref: '#/definitions/NginxStreamKeyvalZone' | |
1360 '404': | |
1361 description: | | |
1362 Keyval not found (*KeyvalNotFound*), | |
1363 keyval key not found (*KeyvalKeyNotFound*), | |
1364 [stream](https://nginx.org/en/docs/stream/ngx_stream_core_module.html#stream) not configured (*StreamNotConfigured*) | |
1365 schema: | |
1366 $ref: '#/definitions/NginxError' | |
1367 post: | |
1368 tags: | |
1369 - Stream Keyvals | |
1370 - Method POST | |
1371 summary: Add a key-value pair to the stream keyval zone | |
1372 description: Adds a new key-value pair to the stream keyval shared memory | |
1373 [zone](https://nginx.org/en/docs/stream/ngx_stream_keyval_module.html#keyval_zone). | |
1374 Several key-value pairs can be entered | |
1375 if the stream keyval shared memory zone is empty. | |
1376 operationId: postStreamKeyvalZoneData | |
1377 produces: | |
1378 - application/json | |
1379 parameters: | |
1380 - in: body | |
1381 name: Key-value | |
1382 description: A key-value pair is specified in the JSON format. | |
1383 Several key-value pairs can be entered | |
1384 if the stream keyval shared memory zone is empty. | |
1385 required: true | |
1386 schema: | |
1387 $ref: '#/definitions/NginxStreamKeyvalZone' | |
1388 responses: | |
1389 '201': | |
1390 description: Created | |
1391 '400': | |
1392 description: | | |
1393 Key required (*KeyvalFormatError*), | |
1394 only one key can be added (*KeyvalFormatError*), | |
1395 nested object or list (*KeyvalFormatError*) | |
1396 schema: | |
1397 $ref: '#/definitions/NginxError' | |
1398 '404': | |
1399 description: | | |
1400 Keyval not found (*KeyvalNotFound*), | |
1401 [stream](https://nginx.org/en/docs/stream/ngx_stream_core_module.html#stream) not configured (*StreamNotConfigured*) | |
1402 schema: | |
1403 $ref: '#/definitions/NginxError' | |
1404 '405': | |
1405 description: Method disabled (*MethodDisabled*) | |
1406 schema: | |
1407 $ref: '#/definitions/NginxError' | |
1408 '409': | |
1409 description: Key already exists (*KeyvalKeyExists*) | |
1410 schema: | |
1411 $ref: '#/definitions/NginxError' | |
1412 '415': | |
1413 description: JSON error (*JsonError*) | |
1414 schema: | |
1415 $ref: '#/definitions/NginxError' | |
1416 patch: | |
1417 tags: | |
1418 - Stream Keyvals | |
1419 - Method PATCH | |
1420 summary: Modify a key-value or delete a key | |
1421 description: Changes the value of the selected key in the key-value pair | |
1422 or deletes a key by setting the key value to <literal>null</literal>. | |
1423 operationId: patchStreamKeyvalZoneKeyValue | |
1424 produces: | |
1425 - application/json | |
1426 parameters: | |
1427 - in: body | |
1428 name: streamKeyvalZoneKeyValue | |
1429 description: A new value for the key is specified in the JSON format. | |
1430 required: true | |
1431 schema: | |
1432 $ref: '#/definitions/NginxStreamKeyvalZone' | |
1433 responses: | |
1434 '204': | |
1435 description: Success | |
1436 '400': | |
1437 description: | | |
1438 Key required (*KeyvalFormatError*), | |
1439 only one key can be updated (*KeyvalFormatError*), | |
1440 nested object or list (*KeyvalFormatError*) | |
1441 schema: | |
1442 $ref: '#/definitions/NginxError' | |
1443 '404': | |
1444 description: | | |
1445 Keyval not found (*KeyvalNotFound*), | |
1446 keyval key not found (*KeyvalKeyNotFound*), | |
1447 [stream](https://nginx.org/en/docs/stream/ngx_stream_core_module.html#stream) not configured (*StreamNotConfigured*) | |
1448 schema: | |
1449 $ref: '#/definitions/NginxError' | |
1450 '405': | |
1451 description: Method disabled (*MethodDisabled*) | |
1452 schema: | |
1453 $ref: '#/definitions/NginxError' | |
1454 '415': | |
1455 description: JSON error (*JsonError*) | |
1456 schema: | |
1457 $ref: '#/definitions/NginxError' | |
1458 delete: | |
1459 tags: | |
1460 - Stream Keyvals | |
1461 - Method DELETE | |
1462 summary: Empty the stream keyval zone | |
1463 description: Deletes all key-value pairs from the stream keyval shared memory | |
1464 [zone](https://nginx.org/en/docs/stream/ngx_stream_keyval_module.html#keyval_zone). | |
1465 operationId: deleteStreamKeyvalZoneData | |
1466 responses: | |
1467 '204': | |
1468 description: Success | |
1469 '404': | |
1470 description: | | |
1471 Keyval not found (*KeyvalNotFound*), | |
1297 [stream](https://nginx.org/en/docs/stream/ngx_stream_core_module.html#stream) not configured (*StreamNotConfigured*) | 1472 [stream](https://nginx.org/en/docs/stream/ngx_stream_core_module.html#stream) not configured (*StreamNotConfigured*) |
1298 schema: | 1473 schema: |
1299 $ref: '#/definitions/NginxError' | 1474 $ref: '#/definitions/NginxError' |
1300 '405': | 1475 '405': |
1301 description: Method disabled (*MethodDisabled*) | 1476 description: Method disabled (*MethodDisabled*) |
2376 down: | 2551 down: |
2377 type: boolean | 2552 type: boolean |
2378 description: Same as the | 2553 description: Same as the |
2379 <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#down">down</a> | 2554 <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#down">down</a> |
2380 parameter of the HTTP upstream server. | 2555 parameter of the HTTP upstream server. |
2556 drain: | |
2557 type: boolean | |
2558 description: Same as the | |
2559 <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#drain">drain</a> | |
2560 parameter of the HTTP upstream server. | |
2381 parent: | 2561 parent: |
2382 type: string | 2562 type: string |
2383 description: Parent server ID of the resolved server. | 2563 description: Parent server ID of the resolved server. |
2384 The ID is assigned automatically and cannot be changed. | 2564 The ID is assigned automatically and cannot be changed. |
2385 readOnly: true | 2565 readOnly: true |
2386 host: | 2566 host: |
2387 type: string | 2567 type: string |
2388 description: Hostname of the resolved server. | 2568 description: Hostname of the resolved server. |
2389 The hostname is assigned automatically and cannot be changed. | 2569 The hostname is assigned automatically and cannot be changed. |
2390 readOnly: true | 2570 readOnly: true |
2391 drain: | |
2392 type: boolean | |
2393 description: Puts the HTTP upstream server into the “draining” mode. | |
2394 In this mode, only requests | |
2395 <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#sticky">bound</a> | |
2396 to the server will be proxied to it. | |
2397 The parameter cannot be initially set, | |
2398 it can only be changed with the <code>PATCH</code> method. | |
2399 example: | 2571 example: |
2400 id: 1 | 2572 id: 1 |
2401 server: 10.0.0.1:8089 | 2573 server: 10.0.0.1:8089 |
2402 weight: 4 | 2574 weight: 4 |
2403 max_conns: 0 | 2575 max_conns: 0 |
2406 slow_start: 10s | 2578 slow_start: 10s |
2407 route: '' | 2579 route: '' |
2408 backup: true | 2580 backup: true |
2409 down: true | 2581 down: true |
2410 NginxHTTPKeyvalZonesMap: | 2582 NginxHTTPKeyvalZonesMap: |
2411 title: Keyval Shared Memory Zones | 2583 title: HTTP Keyval Shared Memory Zones |
2412 description: | | 2584 description: | |
2413 Contents of all keyval shared memory zones. | 2585 Contents of all HTTP keyval shared memory zones. |
2414 type: object | 2586 type: object |
2415 additionalProperties: | 2587 additionalProperties: |
2416 $ref: '#/definitions/NginxHTTPKeyvalZone' | 2588 $ref: '#/definitions/NginxHTTPKeyvalZone' |
2417 example: | 2589 example: |
2418 keyval_zone: | 2590 keyval_zone: |
2422 one: | 2594 one: |
2423 arg1: value1 | 2595 arg1: value1 |
2424 arg2: value2 | 2596 arg2: value2 |
2425 arg3: value3 | 2597 arg3: value3 |
2426 NginxHTTPKeyvalZone: | 2598 NginxHTTPKeyvalZone: |
2427 title: Keyval Shared Memory Zone | 2599 title: HTTP Keyval Shared Memory Zone |
2428 description: | | 2600 description: | |
2429 Contents of a keyval shared memory zone. | 2601 Contents of an HTTP keyval shared memory zone. |
2430 type: object | 2602 type: object |
2431 example: | 2603 example: |
2432 key1: value1 | 2604 key1: value1 |
2433 key2: value2 | 2605 key2: value2 |
2434 key3: value3 | 2606 key3: value3 |
2941 max_fails: 1 | 3113 max_fails: 1 |
2942 fail_timeout: 10s | 3114 fail_timeout: 10s |
2943 slow_start: 0 | 3115 slow_start: 0 |
2944 backup: false | 3116 backup: false |
2945 down: false | 3117 down: false |
3118 NginxStreamKeyvalZonesMap: | |
3119 title: Stream Keyval Shared Memory Zones | |
3120 description: | | |
3121 Contents of all stream keyval shared memory zones. | |
3122 type: object | |
3123 additionalProperties: | |
3124 $ref: '#/definitions/NginxStreamKeyvalZone' | |
3125 example: | |
3126 keyval_zone: | |
3127 key1: value1 | |
3128 key2: value2 | |
3129 key3: value3 | |
3130 one: | |
3131 arg1: value1 | |
3132 arg2: value2 | |
3133 arg3: value3 | |
3134 NginxStreamKeyvalZone: | |
3135 title: Stream Keyval Shared Memory Zone | |
3136 description: | | |
3137 Contents of a stream keyval shared memory zone. | |
3138 type: object | |
3139 example: | |
3140 key1: value1 | |
3141 key2: value2 | |
3142 key3: value3 | |
2946 NginxError: | 3143 NginxError: |
2947 title: Error | 3144 title: Error |
2948 description: | | 3145 description: | |
2949 nginx error object. | 3146 nginx error object. |
2950 type: object | 3147 type: object |