Skip to content

docs: update nginx-one api doc #857

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Jul 21, 2025
Merged

docs: update nginx-one api doc #857

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
570b5b5
docs: update nginx-one api spec
nginx-nickc Jul 18, 2025
dad80f6
docs: fix casing for NGINX
nginx-nickc Jul 21, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
136 changes: 115 additions & 21 deletions static/nginx-one/api/one.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -58,7 +58,7 @@
},
{
"name": "Control Planes",
"description": "The `Control Planes` object represents an external control plane such as NGINX Ingress Controller.\nFrom this endpoint, you can get detailed information about each control plane, including its Nginx instances, configurations, security advisories, and operational status.\n",
"description": "The `Control Planes` object represents an external control plane such as NGINX Ingress Controller.\nFrom this endpoint, you can get detailed information about each control plane, including its NGINX instances, configurations, security advisories, and operational status.\n",
"x-displayName": "Control Planes"
},
{
Expand Down Expand Up @@ -1736,7 +1736,7 @@
"Config Sync Groups"
],
"summary": "Retrieves stored NGINX configurations for a NGINX config sync group",
"description": "Returns a list of all configurations for a NGINX config sync group. Only the last 5 are kept on the NGINX One Console for a NGINX config sync group.",
"description": "Returns a list of all configurations for a NGINX config sync group. Only the last 10 are kept on the NGINX One Console for a NGINX config sync group.",
"operationId": "listConfigSyncGroupConfigurations",
"responses": {
"200": {
Expand Down Expand Up @@ -2201,7 +2201,7 @@
],
"responses": {
"200": {
"description": "Successfully retrieved the list of instances affected by the CVE",
"description": "Successfully retrieved the list of instances affected by the CVE.",
"content": {
"application/json": {
"schema": {
Expand Down Expand Up @@ -2990,7 +2990,7 @@
"Instances"
],
"summary": "Retrieves the stored NGINX configurations for an instance",
"description": "Returns a list of all configurations for a NGINX instance. Only the last 5 are kept on the NGINX One Console for a NGINX instance.",
"description": "Returns a list of all configurations for a NGINX instance. Only the last 10 are kept on the NGINX One Console for a NGINX instance.",
"operationId": "listInstanceConfigurations",
"responses": {
"200": {
Expand Down Expand Up @@ -6378,7 +6378,7 @@
},
"ConfigSyncStatus": {
"type": "string",
"description": "The current config sync status of the NGINX config sync group, with the following possible values:\n* `unknown` - The status cannot be determined at this moment.\n* `in_sync` - All Nginx instances in config sync group have same config as indicated by config_version.\n* `out_of_sync` - Some Nginx instances in config sync group have config different than indicated by config_version.\n* `sync_in_progress` - The operation of applying config_version to all Nginx instances in config sync group is in progress.\n",
"description": "The current config sync status of the NGINX config sync group, with the following possible values:\n* `unknown` - The status cannot be determined at this moment.\n* `in_sync` - All NGINX instances in config sync group have same config as indicated by config_version.\n* `out_of_sync` - Some NGINX instances in config sync group have config different than indicated by config_version.\n* `sync_in_progress` - The operation of applying config_version to all NGINX instances in config sync group is in progress.\n",
"enum": [
"unknown",
"in_sync",
Expand Down Expand Up @@ -6431,6 +6431,7 @@
"required": [
"object_id",
"name",
"created_at",
"instances_count",
"config_status"
],
Expand All @@ -6439,11 +6440,16 @@
"$ref": "#/components/schemas/ConfigSyncGroupObjectID"
},
"name": {
"description": "Name of the Nginx config sync group.",
"description": "Name of the NGINX config sync group.",
"type": "string"
},
"created_at": {
"description": "The date and time when the config sync group was created.",
"type": "string",
"format": "date-time"
},
"instances_count": {
"description": "Number of instances in the Nginx config sync group.",
"description": "Number of instances in the NGINX config sync group.",
"type": "integer"
},
"config_status": {
Expand All @@ -6461,7 +6467,7 @@
},
{
"type": "object",
"description": "List of Nginx config sync groups.",
"description": "List of NGINX config sync groups.",
"required": [
"items"
],
Expand All @@ -6485,21 +6491,22 @@
{
"object_id": "csg_-uvR3F2TQGm18jnl7bpaGw",
"name": "test-config-sync-group",
"created_at": "2023-12-05T22:30:20.220114Z",
"config_status": "in_sync",
"instances_count": 1
}
]
}
},
"ConfigSyncGroupCreateRequest": {
"description": "Body to create a Nginx config sync group.",
"description": "Body to create a NGINX config sync group.",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"description": "A name to uniquely identify the Nginx config sync group in a given tenant namespace.",
"description": "A name to uniquely identify the NGINX config sync group in a given tenant namespace.",
"minLength": 1,
"maxLength": 256
}
Expand All @@ -6509,7 +6516,7 @@
}
},
"ConfigSyncGroupCreateResponse": {
"description": "Response to a create Nginx config sync group request.",
"description": "Response to a create NGINX config sync group request.",
"required": [
"object_id",
"name"
Expand All @@ -6519,7 +6526,7 @@
"$ref": "#/components/schemas/ConfigSyncGroupObjectID"
},
"name": {
"description": "Name of the Nginx config sync group.",
"description": "Name of the NGINX config sync group.",
"type": "string"
}
},
Expand Down Expand Up @@ -6586,7 +6593,7 @@
"$ref": "#/components/schemas/ConfigSyncGroupObjectID"
},
"name": {
"description": "Name of the Nginx config sync group.",
"description": "Name of the NGINX config sync group.",
"type": "string"
},
"last_publication": {
Expand All @@ -6603,7 +6610,8 @@
"example": {
"object_id": "csg_-uvR3F2TQGm18jnl7bpaGw",
"name": "test-config-sync-group",
"last_publication": "2023-12-06T22:37:24.120114Z"
"last_publication": "2023-12-06T22:37:24.120114Z",
"created_at": "2023-12-05T22:30:20.220114Z"
}
},
"InstanceObjectID": {
Expand Down Expand Up @@ -7184,6 +7192,7 @@
"example": {
"object_id": "csg_-uvR3F2TQGm18jnl7bpaGw",
"name": "test-config-sync-group",
"created_at": "2023-12-06T22:37:24.120114Z",
"config_status": "in_sync",
"config_version": "uvR3F2TQGm18jnl7bpaGw",
"instances": [
Expand Down Expand Up @@ -7874,6 +7883,13 @@
"online_instances_count": {
"description": "Total number of online instances in the control plane.",
"type": "integer"
},
"cve_severity": {
"type": "array",
"description": "An array summarizing identified Common Vulnerabilities and Exposures (CVEs) across the NGINX control plane.",
"items": {
"$ref": "#/components/schemas/CveDetails"
}
}
}
}
Expand Down Expand Up @@ -7911,15 +7927,37 @@
"object_id": "ecp_tgfVM3KQTxCyiDXgV38G7A",
"name": "nginx-ingress-001",
"product_version": "nginx-ingress-controller-4.0.1",
"created_at": "2023-12-06T22:37:24.120114Z",
"instances_count": 5,
"online_instances_count": 3
"online_instances_count": 3,
"cve_severity": [
{
"count": 6,
"type": "medium"
},
{
"count": 1,
"type": "high"
}
]
},
{
"object_id": "ecp_-bRQlhscTKmbUIdJaYhGJA",
"name": "nginx-ingress-002",
"created_at": "2023-12-06T22:37:24.120114Z",
"product_version": "nginx-ingress-controller-4.0.1",
"instances_count": 3,
"online_instances_count": 1
"online_instances_count": 1,
"cve_severity": [
{
"count": 2,
"type": "medium"
},
{
"count": 3,
"type": "high"
}
]
}
]
}
Expand Down Expand Up @@ -8002,6 +8040,7 @@
"deployment_uuid": "b9b00e37-5ee4-4361-8c61-1329f3828dd3",
"key_object_id": "key_6AT9LXyUQHyhC8kF7bVMgg",
"kubernetes_namespace": "nginx-ingress-controller",
"created_at": "2023-12-06T22:37:24.120114Z",
"cert_summary": {
"total": 9,
"valid": 1,
Expand Down Expand Up @@ -8045,12 +8084,41 @@
"$ref": "#/components/schemas/SummaryDisplayCount"
}
},
"CveControlPlaneSummary": {
"description": "A summary of Common Vulnerabilities and Exposures (CVEs) across the NGINX control plane.",
"type": "object",
"required": [
"severity",
"count",
"affected_control_planes"
],
"properties": {
"severity": {
"$ref": "#/components/schemas/CveSeverityType"
},
"count": {
"description": "The number of CVEs at each severity level.",
"type": "integer"
},
"affected_control_planes": {
"description": "The number of control planes affected by each CVE.",
"type": "integer"
}
}
},
"ControlPlaneSummary": {
"description": "A summary of control planes including their product names/version details.",
"type": "object",
"properties": {
"product_versions": {
"$ref": "#/components/schemas/ControlPlaneProductVersionSummary"
},
"cves": {
"description": "An array summarizing identified Common Vulnerabilities and Exposures (CVEs) across the NGINX control plane.",
"type": "array",
"items": {
"$ref": "#/components/schemas/CveControlPlaneSummary"
}
}
},
"example": {
Expand All @@ -8059,6 +8127,18 @@
"count": 10,
"name": "nginx-ingress-controller-1.0.0"
}
],
"cves": [
{
"affected_control_planes": 3,
"count": 13,
"severity": "medium"
},
{
"affected_control_planes": 2,
"count": 2,
"severity": "high"
}
]
}
},
Expand Down Expand Up @@ -8087,6 +8167,10 @@
"description": "Number of instances impacted by the security advisory",
"type": "integer"
},
"control_planes_impacted": {
"description": "Number of control planes impacted by the security advisory",
"type": "integer"
},
"published_at": {
"description": "The date and time when the cve was published",
"type": "string",
Expand Down Expand Up @@ -8119,15 +8203,17 @@
},
"NginxProduct": {
"type": "string",
"description": "NGINX product :\n * `noss` - NGINX Open Source.\n * `nplus` - NGINX PLUS.\n",
"description": "NGINX product :\n * `noss` - NGINX Open Source.\n * `nplus` - NGINX PLUS.\n * `nic` - NGINX Ingress Controller.\n",
"enum": [
"noss",
"nplus",
"nic",
"unknown"
],
"x-enum-varnames": [
"nginx_product_noss",
"nginx_product_nplus",
"nginx_product_nic",
"nginx_product_unknown"
]
},
Expand Down Expand Up @@ -8193,6 +8279,13 @@
"1.20.2",
"1.19.9"
]
},
{
"name": "nic",
"versions": [
"1.0.0",
"2.1.0"
]
}
],
"info": "Memory disclosure in the ngx_http_mp4_module",
Expand All @@ -8214,7 +8307,7 @@
"$ref": "#/components/schemas/NginxProduct"
},
"version": {
"description": "version of the Nginx product installed on the instance.",
"description": "version of the NGINX product installed on the instance.",
"type": "string"
}
}
Expand Down Expand Up @@ -8694,7 +8787,8 @@
"control_plane": {
"object_id": "ecp_CO1DdBxZToWmr3pTcaQ8QA",
"name": "nginx-ingress-001",
"product_version": "nginx-ingress-controller-4.0.1"
"product_version": "nginx-ingress-controller-4.0.1",
"created_at": "2023-12-06T22:37:24.120114Z"
},
"last_reported": "2023-12-06T22:37:24.120114Z",
"nginx_build": {
Expand Down Expand Up @@ -8894,7 +8988,7 @@
],
"properties": {
"total": {
"description": "Total count of certificates used as `payloads` in Nginx config.",
"description": "Total count of certificates used as `payloads` in NGINX config.",
"type": "integer"
},
"expired": {
Expand Down Expand Up @@ -10670,9 +10764,9 @@
"value": {
"object_id": "csg_-uvR3F2TQGm18jnl7bpaGw",
"name": "test-config-sync-group",
"last_reported": "2023-12-06T22:37:24.120114Z",
"config_status": "in_sync",
"config_version": "uvR3F2TQGm18jnl7bpaGw",
"created_at": "2023-12-06T22:37:24.120114Z",
"instances": [
{
"object_id": "inst_-uvR3F2TQGm18jnl7bpaGw",
Expand Down
Loading