Mercurial > hg > nginx-site

comparison yaml/nginx_api.yaml @ 2082:fee7627f6a5a

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
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