Skip to content

Commit

Permalink
tweak a few API endpoint summaries and descriptions
Browse files Browse the repository at this point in the history
  • Loading branch information
@david-crespo
david-crespo committed Feb 6, 2024
1 parent d4d8ca2 commit 8237eed
Show file tree
Hide file tree
Showing 2 changed files with 39 additions and 28 deletions.
39 changes: 24 additions & 15 deletions nexus/src/external_api/http_entrypoints.rs
View file
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
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

0 comments on commit 8237eed

Please sign in to comment.