Control Node OpenAPI documentation

implementations/rust/ockam/ockam_api/Cargo.toml

@@ -120,7 +120,7 @@ tracing-error = "0.2.0"
 tracing-opentelemetry = "0.27.0"
 tracing-subscriber = { version = "0.3", features = ["json"] }
 url = "2.5.2"
-utoipa = { version = "^5.3", features = ["yaml"] }
+utoipa = { version = "^5.3", features = ["yaml", "openapi_extensions"] }
 
 ockam_multiaddr = { path = "../ockam_multiaddr", version = "0.69.0", features = ["cbor", "serde"] }
 ockam_transport_core = { path = "../ockam_transport_core", version = "^0.101.0" }

implementations/rust/ockam/ockam_api/src/control_api/backend/authority_member.rs

@@ -1,57 +1,53 @@
 use crate::authenticator::direct::Members;
 use crate::control_api::backend::common;
-use crate::control_api::backend::common::create_authority_client;
+use crate::control_api::backend::common::{create_authority_client, ResourceKind};
 use crate::control_api::backend::entrypoint::HttpControlNodeApiBackend;
 use crate::control_api::http::ControlApiHttpResponse;
 use crate::control_api::protocol::authority_member::{
     AddOrUpdateAuthorityMemberRequest, AuthorityMember, GetAuthorityMemberRequest,
     ListAuthorityMembersRequest, RemoveAuthorityMemberRequest,
 };
+use crate::control_api::protocol::common::{Attributes, ErrorResponse, NodeName};
 use crate::control_api::ControlApiError;
 use crate::nodes::NodeManager;
-use http::StatusCode;
+use http::{Method, StatusCode};
 use ockam_node::Context;
 use std::sync::Arc;
 
 impl HttpControlNodeApiBackend {
     pub(super) async fn handle_authority_member(
         &self,
         context: &Context,
-        method: &str,
+        method: Method,
         resource_id: Option<&str>,
         body: Option<Vec<u8>>,
     ) -> Result<ControlApiHttpResponse, ControlApiError> {
-        let resource_name = "authority-member";
-        let resource_name_identifier = "authority_member_identity";
         match method {
-            "PUT" => match resource_id {
-                None => ControlApiHttpResponse::missing_resource_id(
-                    resource_name,
-                    resource_name_identifier,
-                ),
+            Method::PUT => match resource_id {
+                None => ControlApiHttpResponse::missing_resource_id(ResourceKind::AuthorityMembers),
                 Some(id) => {
                     handle_authority_member_add_or_update(context, &self.node_manager, body, id)
                         .await
                 }
             },
-            "GET" => match resource_id {
+            Method::GET => match resource_id {
                 None => handle_authority_member_list(context, &self.node_manager, body).await,
                 Some(id) => {
                     handle_authority_member_get(context, &self.node_manager, body, id).await
                 }
             },
-            "DELETE" => match resource_id {
-                None => ControlApiHttpResponse::missing_resource_id(
-                    resource_name,
-                    resource_name_identifier,
-                ),
+            Method::DELETE => match resource_id {
+                None => ControlApiHttpResponse::missing_resource_id(ResourceKind::AuthorityMembers),
                 Some(id) => {
                     handle_authority_member_remove(context, &self.node_manager, body, id).await
                 }
             },
             _ => {
                 warn!("Invalid method: {method}");
-                ControlApiHttpResponse::invalid_method(method, vec!["PUT", "GET", "DELETE"])
+                ControlApiHttpResponse::invalid_method(
+                    method,
+                    vec![Method::PUT, Method::GET, Method::DELETE],
+                )
             }
         }
     }
@@ -61,13 +57,17 @@ impl HttpControlNodeApiBackend {
     put,
     operation_id = "add_or_update_authority_member",
     summary = "Add or update an Authority Member",
-    path = "/{node}/authority-member/{member}",
-    tags = ["authority-member"],
+    description =
+"Add or update an Authority Member with the specified attributes.
+Attributes will overwrite the existing ones if the member already exists.",
+    path = "/{node}/authority-members/{member}",
+    tags = ["Authority Members"],
     responses(
         (status = CREATED, description = "Successfully created"),
+        (status = NOT_FOUND, description = "Specified project not found", body = ErrorResponse),
     ),
     params(
-        ("node" = String, description = "Destination node name"),
+        ("node" = NodeName,),
         ("member" = String, description = "Member identity", example = "Id3b788c6a89de8b1f2fd13743eb3123178cf6ec7c9253be8ddcf7e154abe016a"),
     ),
     request_body(
@@ -90,7 +90,7 @@ async fn handle_authority_member_add_or_update(
         create_authority_client(node_manager, &request.authority, &request.identity).await?;
 
     let result = authority_client
-        .add_member(context, member_identity, request.attributes)
+        .add_member(context, member_identity, request.attributes.0)
         .await;
     match result {
         Ok(_) => Ok(ControlApiHttpResponse::without_body(StatusCode::CREATED)?),
@@ -105,18 +105,20 @@ async fn handle_authority_member_add_or_update(
     get,
     operation_id = "list_authority_members",
     summary = "List Authority Members",
-    path = "/{node}/authority-member",
-    tags = ["authority-member"],
+    description = "List all members of the Authority.",
+    path = "/{node}/authority-members",
+    tags = ["Authority Members"],
     responses(
         (status = OK, description = "Successfully retrieved", body = Vec<AuthorityMember>),
+        (status = NOT_FOUND, description = "Specified project not found", body = ErrorResponse),
     ),
     params(
-        ("node" = String, description = "Destination node name"),
+        ("node" = NodeName,),
     ),
     request_body(
         content = ListAuthorityMembersRequest,
         content_type = "application/json",
-        description = "Creation request"
+        description = "Optional list request"
     )
 )]
 async fn handle_authority_member_list(
@@ -136,7 +138,7 @@ async fn handle_authority_member_list(
                 .into_iter()
                 .map(|(identity, attributes_entry)| AuthorityMember {
                     identity: identity.to_string(),
-                    attributes: attributes_entry.string_attributes(),
+                    attributes: Attributes(attributes_entry.string_attributes()),
                 })
                 .collect();
             Ok(ControlApiHttpResponse::with_body(StatusCode::OK, members)?)
@@ -152,19 +154,21 @@ async fn handle_authority_member_list(
     get,
     operation_id = "get_authority_member",
     summary = "Get Authority Member",
-    path = "/{node}/authority-member/{member}",
-    tags = ["authority-member"],
+    description = "Get the specified member of the Authority by identity.",
+    path = "/{node}/authority-members/{member}",
+    tags = ["Authority Members"],
     responses(
         (status = OK, description = "Successfully retrieved", body = AuthorityMember),
+        (status = NOT_FOUND, description = "Specified project not found", body = ErrorResponse),
     ),
     params(
-        ("node" = String, description = "Destination node name"),
+        ("node" = NodeName,),
         ("member" = String, description = "Member identity", example = "Id3b788c6a89de8b1f2fd13743eb3123178cf6ec7c9253be8ddcf7e154abe016a"),
     ),
     request_body(
         content = GetAuthorityMemberRequest,
         content_type = "application/json",
-        description = "Get member request"
+        description = "Optional get member request"
     )
 )]
 async fn handle_authority_member_get(
@@ -188,7 +192,7 @@ async fn handle_authority_member_get(
             StatusCode::OK,
             AuthorityMember {
                 identity: member_identity.to_string(),
-                attributes: attributes_entry.string_attributes(),
+                attributes: Attributes(attributes_entry.string_attributes()),
             },
         )?),
         Err(error) => {
@@ -203,19 +207,21 @@ async fn handle_authority_member_get(
     delete,
     operation_id = "remove_authority_member",
     summary = "Remove an Authority Member",
-    path = "/{node}/authority-member/{member}",
-    tags = ["authority-member"],
+    description = "Remove the specified member of the Authority by identity.",
+    path = "/{node}/authority-members/{member}",
+    tags = ["Authority Members"],
     responses(
         (status = OK, description = "Successfully removed"),
+        (status = NOT_FOUND, description = "Specified project not found", body = ErrorResponse),
     ),
     params(
-        ("node" = String, description = "Destination node name"),
+        ("node" = NodeName,),
         ("member" = String, description = "Member identity", example = "Id3b788c6a89de8b1f2fd13743eb3123178cf6ec7c9253be8ddcf7e154abe016a"),
     ),
     request_body(
         content = RemoveAuthorityMemberRequest,
         content_type = "application/json",
-        description = "Remove member request"
+        description = "Optional remove member request"
     )
 )]
 async fn handle_authority_member_remove(

implementations/rust/ockam/ockam_api/src/control_api/backend/common.rs

@@ -1,16 +1,91 @@
 use crate::control_api::http::ControlApiHttpResponse;
-use crate::control_api::protocol::common::Authority;
+use crate::control_api::protocol::common::{Authority, ErrorResponse};
 use crate::control_api::ControlApiError;
 use crate::nodes::NodeManager;
 use crate::orchestrator::project::Project;
 use crate::orchestrator::AuthorityNodeClient;
+use http::StatusCode;
 use ockam::identity::Identifier;
 use ockam_core::errcode::{Kind, Origin};
 use ockam_multiaddr::MultiAddr;
 use serde::de::DeserializeOwned;
+use std::fmt::Display;
 use std::str::FromStr;
 use std::sync::Arc;
 
+pub(super) enum ResourceKind {
+    TcpInlets,
+    TcpOutlets,
+    Relays,
+    Tickets,
+    AuthorityMembers,
+}
+
+impl ResourceKind {
+    pub fn enumerate() -> Vec<Self> {
+        vec![
+            Self::TcpInlets,
+            Self::TcpOutlets,
+            Self::Relays,
+            Self::Tickets,
+            Self::AuthorityMembers,
+        ]
+    }
+    pub fn from_str(resource: &str) -> Option<Self> {
+        match resource {
+            "tcp-inlets" => Some(Self::TcpInlets),
+            "tcp-outlets" => Some(Self::TcpOutlets),
+            "relays" => Some(Self::Relays),
+            "tickets" => Some(Self::Tickets),
+            "authority-members" => Some(Self::AuthorityMembers),
+            _ => None,
+        }
+    }
+
+    pub fn name(&self) -> &'static str {
+        match self {
+            Self::TcpInlets => "tcp-inlets",
+            Self::TcpOutlets => "tcp-outlets",
+            Self::Relays => "relays",
+            Self::Tickets => "tickets",
+            Self::AuthorityMembers => "authority-members",
+        }
+    }
+
+    pub fn parameter_name(&self) -> &'static str {
+        match self {
+            Self::TcpInlets => "inlet_name",
+            Self::TcpOutlets => "outlet_address",
+            Self::Relays => "relay_name",
+            Self::Tickets => "",
+            Self::AuthorityMembers => "authority_member",
+        }
+    }
+}
+
+impl Display for ResourceKind {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(f, "{}", self.name())
+    }
+}
+
+impl ControlApiHttpResponse {
+    pub(super) fn missing_resource_id<T>(
+        resource_kind: ResourceKind,
+    ) -> Result<T, ControlApiError> {
+        let resource_name = resource_kind.name();
+        let resource_name_identifier = resource_kind.parameter_name();
+
+        Err(Self::with_body(
+            StatusCode::BAD_REQUEST,
+            ErrorResponse {
+                message: format!("Missing parameter {resource_name}. The HTTP path should be /{{node-name}}/{resource_name}/{{{resource_name_identifier}}}"),
+            },
+        )?
+            .into())
+    }
+}
+
 pub async fn create_authority_client(
     node_manager: &Arc<NodeManager>,
     authority: &Authority,
@@ -61,7 +136,7 @@ pub async fn create_authority_client(
                 }
                 Err(error) => {
                     warn!("No default project: {error:?}");
-                    return ControlApiHttpResponse::bad_request("No default project");
+                    return ControlApiHttpResponse::not_found("Default project not found");
                 }
             }
         }