Skip to content
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

Tweak a few API endpoint summaries and descriptions #4999

Merged
merged 1 commit into from
Feb 6, 2024
Merged

Tweak a few API endpoint summaries and descriptions #4999

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
39 changes: 24 additions & 15 deletions nexus/src/external_api/http_entrypoints.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -759,7 +759,11 @@ async fn silo_view(
apictx.external_latencies.instrument_dropshot_handler(&rqctx, handler).await
}

/// List IP pools available within silo
/// List IP pools linked to silo
///
/// Linked IP pools are available to users in the specified silo. A silo can
/// have at most one default pool. IPs are allocated from the default pool when
/// users ask for one without specifying a pool.
#[endpoint {
method = GET,
path = "/v1/system/silos/{silo}/ip-pools",
Expand Down Expand Up @@ -803,7 +807,7 @@ async fn silo_ip_pool_list(

/// Delete a silo
///
/// Delete a silo by name.
/// Delete a silo by name or ID.
#[endpoint {
method = DELETE,
path = "/v1/system/silos/{silo}",
Expand Down Expand Up @@ -1569,7 +1573,11 @@ async fn ip_pool_silo_list(
apictx.external_latencies.instrument_dropshot_handler(&rqctx, handler).await
}

/// Make an IP pool available within a silo
/// Link an IP pool to a silo
///
/// Users in linked silos can allocate external IPs from this pool for their
/// instances. A silo can have at most one default pool. IPs are allocated from
/// the default pool when users ask for one without specifying a pool.
#[endpoint {
method = POST,
path = "/v1/system/ip-pools/{pool}/silos",
Expand Down Expand Up @@ -1620,10 +1628,12 @@ async fn ip_pool_silo_unlink(
apictx.external_latencies.instrument_dropshot_handler(&rqctx, handler).await
}

/// Make an IP pool default or not-default for a silo
/// Make IP pool default for silo
///
/// When a pool is made default for a silo, any existing default will remain
/// linked to the silo, but will no longer be the default.
/// When a user asks for an IP (e.g., at instance create time) without
/// specifying a pool, the IP comes from the default pool if a default is
/// configured. When a pool is made the default for a silo, any existing default
/// will remain linked to the silo, but will no longer be the default.
#[endpoint {
method = PUT,
path = "/v1/system/ip-pools/{pool}/silos/{silo}",
Expand All @@ -1650,7 +1660,7 @@ async fn ip_pool_silo_update(
apictx.external_latencies.instrument_dropshot_handler(&rqctx, handler).await
}

/// Fetch the IP pool used for Oxide services
/// Fetch the Oxide service IP pool
#[endpoint {
method = GET,
path = "/v1/system/ip-pools-service",
Expand Down Expand Up @@ -1765,10 +1775,9 @@ async fn ip_pool_range_remove(
apictx.external_latencies.instrument_dropshot_handler(&rqctx, handler).await
}

/// List ranges for the IP pool used for Oxide services
/// List IP ranges for the Oxide service pool
///
/// List ranges for the IP pool used for Oxide services. Ranges are ordered by
/// their first address.
/// Ranges are ordered by their first address.
#[endpoint {
method = GET,
path = "/v1/system/ip-pools-service/ranges",
Expand Down Expand Up @@ -1809,7 +1818,7 @@ async fn ip_pool_service_range_list(
apictx.external_latencies.instrument_dropshot_handler(&rqctx, handler).await
}

/// Add a range to an IP pool used for Oxide services
/// Add IP range to Oxide service pool
#[endpoint {
method = POST,
path = "/v1/system/ip-pools-service/ranges/add",
Expand All @@ -1830,7 +1839,7 @@ async fn ip_pool_service_range_add(
apictx.external_latencies.instrument_dropshot_handler(&rqctx, handler).await
}

/// Remove a range from an IP pool used for Oxide services
/// Remove IP range from Oxide service pool
#[endpoint {
method = POST,
path = "/v1/system/ip-pools-service/ranges/remove",
Expand Down Expand Up @@ -3539,7 +3548,7 @@ async fn networking_bgp_announce_set_delete(
apictx.external_latencies.instrument_dropshot_handler(&rqctx, handler).await
}

/// Enable a BFD session.
/// Enable a BFD session
#[endpoint {
method = POST,
path = "/v1/system/networking/bfd-enable",
Expand All @@ -3560,7 +3569,7 @@ async fn networking_bfd_enable(
apictx.external_latencies.instrument_dropshot_handler(&rqctx, handler).await
}

/// Disable a BFD session.
/// Disable a BFD session
#[endpoint {
method = POST,
path = "/v1/system/networking/bfd-disable",
Expand All @@ -3581,7 +3590,7 @@ async fn networking_bfd_disable(
apictx.external_latencies.instrument_dropshot_handler(&rqctx, handler).await
}

/// Get BFD status.
/// Get BFD status
#[endpoint {
method = GET,
path = "/v1/system/networking/bfd-status",
Expand Down
28 changes: 15 additions & 13 deletions openapi/nexus.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5331,7 +5331,8 @@
"tags": [
"system/networking"
],
"summary": "Make an IP pool available within a silo",
"summary": "Link an IP pool to a silo",
"description": "Users in linked silos can allocate external IPs from this pool for their instances. A silo can have at most one default pool. IPs are allocated from the default pool when users ask for one without specifying a pool.",
"operationId": "ip_pool_silo_link",
"parameters": [
{
Expand Down Expand Up @@ -5379,8 +5380,8 @@
"tags": [
"system/networking"
],
"summary": "Make an IP pool default or not-default for a silo",
"description": "When a pool is made default for a silo, any existing default will remain linked to the silo, but will no longer be the default.",
"summary": "Make IP pool default for silo",
"description": "When a user asks for an IP (e.g., at instance create time) without specifying a pool, the IP comes from the default pool if a default is configured. When a pool is made the default for a silo, any existing default will remain linked to the silo, but will no longer be the default.",
"operationId": "ip_pool_silo_update",
"parameters": [
{
Expand Down Expand Up @@ -5472,7 +5473,7 @@
"tags": [
"system/networking"
],
"summary": "Fetch the IP pool used for Oxide services",
"summary": "Fetch the Oxide service IP pool",
"operationId": "ip_pool_service_view",
"responses": {
"200": {
Expand All @@ -5499,8 +5500,8 @@
"tags": [
"system/networking"
],
"summary": "List ranges for the IP pool used for Oxide services",
"description": "List ranges for the IP pool used for Oxide services. Ranges are ordered by their first address.",
"summary": "List IP ranges for the Oxide service pool",
"description": "Ranges are ordered by their first address.",
"operationId": "ip_pool_service_range_list",
"parameters": [
{
Expand Down Expand Up @@ -5552,7 +5553,7 @@
"tags": [
"system/networking"
],
"summary": "Add a range to an IP pool used for Oxide services",
"summary": "Add IP range to Oxide service pool",
"operationId": "ip_pool_service_range_add",
"requestBody": {
"content": {
Expand Down Expand Up @@ -5589,7 +5590,7 @@
"tags": [
"system/networking"
],
"summary": "Remove a range from an IP pool used for Oxide services",
"summary": "Remove IP range from Oxide service pool",
"operationId": "ip_pool_service_range_remove",
"requestBody": {
"content": {
Expand Down Expand Up @@ -5909,7 +5910,7 @@
"tags": [
"system/networking"
],
"summary": "Disable a BFD session.",
"summary": "Disable a BFD session",
"operationId": "networking_bfd_disable",
"requestBody": {
"content": {
Expand Down Expand Up @@ -5939,7 +5940,7 @@
"tags": [
"system/networking"
],
"summary": "Enable a BFD session.",
"summary": "Enable a BFD session",
"operationId": "networking_bfd_enable",
"requestBody": {
"content": {
Expand Down Expand Up @@ -5969,7 +5970,7 @@
"tags": [
"system/networking"
],
"summary": "Get BFD status.",
"summary": "Get BFD status",
"operationId": "networking_bfd_status",
"responses": {
"200": {
Expand Down Expand Up @@ -6980,7 +6981,7 @@
"system/silos"
],
"summary": "Delete a silo",
"description": "Delete a silo by name.",
"description": "Delete a silo by name or ID.",
"operationId": "silo_delete",
"parameters": [
{
Expand Down Expand Up @@ -7011,7 +7012,8 @@
"tags": [
"system/silos"
],
"summary": "List IP pools available within silo",
"summary": "List IP pools linked to silo",
"description": "Linked IP pools are available to users in the specified silo. A silo can have at most one default pool. IPs are allocated from the default pool when users ask for one without specifying a pool.",
"operationId": "silo_ip_pool_list",
"parameters": [
{
Expand Down
Loading