Security/corrections (#142)

* A collection of small corrections for Security API spec. - Added missing `security.update_all_distinguished_names` Operation. - Corrected x-operation-group: `security.get_roles_mapping -> security.get_role_mappings` - Renamed Message and `MessageStatus -> SecurityOperationStatus` and `Message -> SecurityOperationMessage` for better clarity. - Renamed `GetAuditConfig -> GetAuditConfiguration`, `PatchAuditConfig -> PatchAuditConfiguration`, and `UpdateAuditConfig -> UpdateAuditConfiguration` (along with their `x-operation-group`s) to match the naming in the [released Python client for Security namespace](https://github.com/opensearch-project/opensearch-py/blob/main/opensearchpy/client/security.py), and to stay consistent with other operations like `UpdateConfiguration` - Reordered model definitions so that the structures closer to the root of of a multi-level map are defined first, for better readability. - Corrected API Reference links - Updated operation descriptions to have consistent language and more in-line with the API docs. - Added missing descriptions. - Corrected `audit.smithy -> audit_config.smithy` file. - Moved `AuditConfigWithReadOnly` and `AuditConfigReadOnlyList` to `model/security/audit_config.smithy` Signed-off-by: Theo Truong <[email protected]> * replaced `_opendistro` with `_plugins` Signed-off-by: Theo Truong <[email protected]> * renamed Flush_Cache to FlushCache Signed-off-by: Theo Truong <[email protected]> * renamed UpdateAllDistinguishedNames to PatchDistinguishedNames Signed-off-by: Theo Truong <[email protected]> * moved GetDistinguishedNamesWithClusterName into the same location as GetDistinguishedNames since they are of the same operation group. Signed-off-by: Theo Truong <[email protected]> --------- Signed-off-by: Theo Truong <[email protected]>
opensearch-project · Aug 15, 2023 · 561f5ba · 561f5ba
1 parent fb20015
commit 561f5ba
Show file tree

Hide file tree

Showing 67 changed files with 232 additions and 193 deletions.
diff --git a/model/opensearch.smithy b/model/opensearch.smithy
@@ -188,13 +188,13 @@ service OpenSearch {
         FieldCaps_Get_WithIndex,
         FieldCaps_Post,
         FieldCaps_Post_WithIndex,
-        Flush_Cache,
+        FlushCache,
         Get,
         GetAccountDetails,
         GetAllPits,
         GetActionGroup,
         GetActionGroups,
-        GetAuditConfig,
+        GetAuditConfiguration,
         GetCertificates,
         GetConfiguration,
         GetDistinguishedNames,
@@ -361,8 +361,9 @@ service OpenSearch {
         NodesUsage_WithNodeId,
         PatchActionGroup,
         PatchActionGroups,
-        PatchAuditConfig,
+        PatchAuditConfiguration,
         PatchConfiguration,
+        PatchDistinguishedNames,
         PatchRole,
         PatchRoles,
         PatchTenant,
@@ -433,7 +434,7 @@ service OpenSearch {
         Termvectors_Post,
         Termvectors_Post_WithId,
         Update,
-        UpdateAuditConfig,
+        UpdateAuditConfiguration,
         UpdateByQuery,
         UpdateByQueryRethrottle,
         UpdateConfiguration,

diff --git a/model/security/action_group.smithy b/model/security/action_group.smithy
@@ -7,11 +7,12 @@
 $version: "2"
 namespace OpenSearch
 
-list AllowedActions {
-    member: String
+map ActionGroupsMap {
+  key: String,
+  value: Action_Group
 }
 
-structure Action_Group{
+structure Action_Group {
     reserved: Boolean,
     hidden: Boolean,
     allowed_actions: AllowedActions,
@@ -20,7 +21,6 @@ structure Action_Group{
     static: Boolean
 }
 
-map ActionGroupsMap {
-     key: String,
-     value: Action_Group
+list AllowedActions {
+  member: String
 }
diff --git a/model/security/audit.smithy → model/security/audit_config.smithy b/model/security/audit.smithy → model/security/audit_config.smithy
@@ -7,6 +7,15 @@
 $version: "2"
 namespace OpenSearch
 
+structure AuditConfigWithReadOnly {
+    _readonly: AuditConfigReadOnlyList,
+    config: AuditConfig
+}
+
+list AuditConfigReadOnlyList {
+    member: String
+}
+
 structure AuditConfig {
     compliance: ComplianceConfig
     enabled: Boolean
@@ -16,7 +25,7 @@ structure AuditConfig {
 structure ComplianceConfig {
     enabled: Boolean
     write_log_diffs: Boolean
-    read_watched_fields: AttributesMap
+    read_watched_fields: Document
     read_ignore_users: IgnoreUsersList
     write_watched_indices: WriteWatchedIndices
     write_ignore_users: WriteIgnoreUsers

diff --git a/model/security/change_password/operations.smithy b/model/security/change_password/operations.smithy
@@ -9,7 +9,7 @@ namespace OpenSearch
 use opensearch.openapi#vendorExtensions
 
 @externalDocumentation(
-    "API Reference": "https://opensearch.org/docs/latest/security/access-control/api/"
+    "API Reference": "https://opensearch.org/docs/latest/security/access-control/api/#change-password"
 )
 
 @vendorExtensions(

diff --git a/model/security/change_password/structures.smithy b/model/security/change_password/structures.smithy
@@ -10,13 +10,15 @@ namespace OpenSearch
 @input
 structure ChangePassword_Input{
     @required
+    @documentation("The current password")
     current_password: String
     @required
+    @documentation("The new password to set")
     password: String
 }
 
 @output
 structure ChangePassword_Output{
-    status: MessageStatus,
-    message: Message
+    status: SecurityOperationStatus,
+    message: SecurityOperationMessage
 }
diff --git a/model/security/create_action_group/structures.smithy b/model/security/create_action_group/structures.smithy
@@ -11,13 +11,14 @@ namespace OpenSearch
 structure CreateActionGroup_Input {
     @required
     @httpLabel
+    @documentation("The name of the action group to create or replace")
     action_group: String
     @httpPayload
     content: Action_Group
 }
 
 @output
 structure CreateActionGroup_Output {
-    status: MessageStatus,
-    message: Message
+    status: SecurityOperationStatus,
+    message: SecurityOperationMessage
 }
diff --git a/model/security/create_role/structures.smithy b/model/security/create_role/structures.smithy
@@ -20,6 +20,6 @@ structure CreateRole_Input{
 
 @output
 structure CreateRole_Output {
-    status: MessageStatus,
-    message: Message
+    status: SecurityOperationStatus,
+    message: SecurityOperationMessage
 }
diff --git a/model/security/create_role_mapping/structures.smithy b/model/security/create_role_mapping/structures.smithy
@@ -20,6 +20,6 @@ structure CreateRoleMapping_Input{
 
 @output
 structure CreateRoleMapping_Output {
-    status: MessageStatus,
-    message: Message
+    status: SecurityOperationStatus,
+    message: SecurityOperationMessage
 }
diff --git a/model/security/create_tenant/structures.smithy b/model/security/create_tenant/structures.smithy
@@ -18,8 +18,8 @@ structure CreateTenant_Input {
 
 @output
 structure CreateTenant_Output {
-    status: MessageStatus,
-    message: Message
+    status: SecurityOperationStatus,
+    message: SecurityOperationMessage
 }
 
 structure CreateTenantParams{

diff --git a/model/security/create_user/structures.smithy b/model/security/create_user/structures.smithy
@@ -20,6 +20,6 @@ structure CreateUser_Input {
 
 @output
 structure CreateUser_Output {
-    status: MessageStatus
-    message: Message
+    status: SecurityOperationStatus
+    message: SecurityOperationMessage
 }
diff --git a/model/security/delete_action_group/operations.smithy b/model/security/delete_action_group/operations.smithy
@@ -19,7 +19,7 @@ use opensearch.openapi#vendorExtensions
 @readonly
 @suppress(["HttpUriConflict", "HttpMethodSemantics.UnexpectedPayload"])
 @http(method: "DELETE", uri: "/_plugins/_security/api/actiongroups/{action_group}")
-@documentation("Delete specified action group.")
+@documentation("Delete a specified action group.")
 operation DeleteActionGroup {
     input: DeleteActionGroup_Input,
     output: DeleteActionGroup_Output

diff --git a/model/security/delete_action_group/structures.smithy b/model/security/delete_action_group/structures.smithy
@@ -11,11 +11,12 @@ namespace OpenSearch
 structure DeleteActionGroup_Input{
     @required
     @httpLabel
+    @documentation("Action group to delete.")
     action_group: String
 }
 
 @output
 structure DeleteActionGroup_Output {
-    status: MessageStatus,
-    message: Message
+    status: SecurityOperationStatus,
+    message: SecurityOperationMessage
 }
diff --git a/model/security/delete_distinguished_names/structures.smithy b/model/security/delete_distinguished_names/structures.smithy
@@ -16,6 +16,6 @@ structure DeleteDistinguishedNames_Input {
 
 @output
 structure DeleteDistinguishedNames_Output {
-    status: MessageStatus,
-    message: Message
+    status: SecurityOperationStatus,
+    message: SecurityOperationMessage
 }
diff --git a/model/security/delete_role/operations.smithy b/model/security/delete_role/operations.smithy
@@ -19,7 +19,7 @@ use opensearch.openapi#vendorExtensions
 @idempotent
 @suppress(["HttpUriConflict"])
 @http(method: "DELETE", uri: "/_plugins/_security/api/roles/{role}")
-@documentation("Delete role.")
+@documentation("Delete the specified role.")
 operation DeleteRole {
     input: DeleteRole_Input,
     output: DeleteRole_Output

diff --git a/model/security/delete_role/structures.smithy b/model/security/delete_role/structures.smithy
@@ -16,6 +16,6 @@ structure DeleteRole_Input{
 
 @output
 structure DeleteRole_Output {
-    status: MessageStatus,
-    message: Message
+    status: SecurityOperationStatus,
+    message: SecurityOperationMessage
 }
diff --git a/model/security/delete_role_mapping/structures.smithy b/model/security/delete_role_mapping/structures.smithy
@@ -7,7 +7,6 @@
 $version: "2"
 namespace OpenSearch
 
-
 @input
 structure DeleteRoleMapping_Input{
     @required
@@ -17,6 +16,6 @@ structure DeleteRoleMapping_Input{
 
 @output
 structure DeleteRoleMapping_Output {
-    status: MessageStatus,
-    message: Message
+    status: SecurityOperationStatus,
+    message: SecurityOperationMessage
 }
diff --git a/model/security/delete_tenant/structures.smithy b/model/security/delete_tenant/structures.smithy
@@ -16,6 +16,6 @@ structure DeleteTenant_Input{
 
 @output
 structure DeleteTenant_Output {
-    status: MessageStatus,
-    message: Message
+    status: SecurityOperationStatus,
+    message: SecurityOperationMessage
 }
diff --git a/model/security/delete_user/structures.smithy b/model/security/delete_user/structures.smithy
@@ -17,6 +17,6 @@ structure DeleteUser_Input {
 
 @output
 structure DeleteUser_Output {
-    status: MessageStatus,
-    message: Message
+    status: SecurityOperationStatus,
+    message: SecurityOperationMessage
 }
diff --git a/model/security/distinguished_name.smithy b/model/security/distinguished_name.smithy
@@ -7,13 +7,15 @@
 $version: "2"
 namespace OpenSearch
 
+map DistinguishedNamesMap {
+    key: String,
+    value: DistinguishedNames
+}
+
 structure DistinguishedNames {
     nodes_dn: NodesDn
 }
+
 list NodesDn {
     member: String
 }
-map DistinguishedNamesMap {
-    key: String,
-    value: DistinguishedNames
-}
diff --git a/model/security/flush_cache/operations.smithy b/model/security/flush_cache/operations.smithy
@@ -20,7 +20,7 @@ use opensearch.openapi#vendorExtensions
 @idempotent
 @http(method: "DELETE", uri: "/_plugins/_security/api/cache")
 @documentation("Flushes the Security plugin user, authentication, and authorization cache.")
-operation Flush_Cache {
-    input: Flush_Cache_Input,
-    output: Flush_Cache_Output
+operation FlushCache {
+    input: FlushCache_Input,
+    output: FlushCache_Output
 }
diff --git a/model/security/flush_cache/structures.smithy b/model/security/flush_cache/structures.smithy
@@ -8,10 +8,10 @@ $version: "2"
 namespace OpenSearch
 
 @input
-structure Flush_Cache_Input {}
+structure FlushCache_Input {}
 
 @output
-structure Flush_Cache_Output {
-    status: MessageStatus,
-    message: Message
+structure FlushCache_Output {
+    status: SecurityOperationStatus,
+    message: SecurityOperationMessage
 }
diff --git a/model/security/get_account_details/operations.smithy b/model/security/get_account_details/operations.smithy
@@ -9,7 +9,7 @@ namespace OpenSearch
 use opensearch.openapi#vendorExtensions
 
 @externalDocumentation(
-    "API Reference": "https://opensearch.org/docs/latest/security/access-control/api/"
+    "API Reference": "https://opensearch.org/docs/latest/security/access-control/api/#get-account-details"
 )
 
 @vendorExtensions(

diff --git a/model/security/get_action_group/operations.smithy b/model/security/get_action_group/operations.smithy
@@ -19,7 +19,7 @@ use opensearch.openapi#vendorExtensions
 @readonly
 @suppress(["HttpUriConflict", "HttpMethodSemantics.UnexpectedPayload"])
 @http(method: "GET", uri: "/_plugins/_security/api/actiongroups/{action_group}")
-@documentation("Providing information about given action group.")
+@documentation("Retrieves one action group.")
 operation GetActionGroup {
     input: GetActionGroup_Input,
     output: GetActionGroup_Output

diff --git a/model/security/get_action_group/structures.smithy b/model/security/get_action_group/structures.smithy
@@ -11,6 +11,7 @@ namespace OpenSearch
 structure GetActionGroup_Input{
     @required
     @httpLabel
+    @documentation("Action group to retrieve.")
     action_group: String
 }
 

diff --git a/model/security/get_action_groups/operations.smithy b/model/security/get_action_groups/operations.smithy
@@ -19,7 +19,7 @@ use opensearch.openapi#vendorExtensions
 @readonly
 @suppress(["HttpUriConflict"])
 @http(method: "GET", uri: "/_plugins/_security/api/actiongroups/")
-@documentation("Lists of all action groups.")
+@documentation("Retrieves all action groups.")
 operation GetActionGroups {
     input: GetActionGroups_Input,
     output: GetActionGroups_Output

diff --git a/model/security/get_audit/operations.smithy → ...get_audit_configuration/operations.smithy b/model/security/get_audit/operations.smithy → ...get_audit_configuration/operations.smithy
@@ -13,14 +13,14 @@ use opensearch.openapi#vendorExtensions
 )
 
 @vendorExtensions(
-    "x-operation-group": "security.get_audit_config",
+    "x-operation-group": "security.get_audit_configuration",
     "x-version-added": "1.0",
 )
 @readonly
 @suppress(["HttpUriConflict"])
-@http(method: "GET", uri: "/_opendistro/_security/api/audit")
-@documentation("A GET call retrieves the audit configuration.")
-operation GetAuditConfig {
-    input: GetAuditConfig_Input,
-    output: GetAuditConfig_Output
+@http(method: "GET", uri: "/_plugins/_security/api/audit")
+@documentation("Retrieves the audit configuration.")
+operation GetAuditConfiguration {
+    input: GetAuditConfiguration_Input,
+    output: GetAuditConfiguration_Output
 }
diff --git a/model/security/get_audit/structures.smithy → ...get_audit_configuration/structures.smithy b/model/security/get_audit/structures.smithy → ...get_audit_configuration/structures.smithy
@@ -8,20 +8,11 @@ $version: "2"
 namespace OpenSearch
 
 @input
-structure GetAuditConfig_Input{
+structure GetAuditConfiguration_Input{
 }
 
 @output
-structure GetAuditConfig_Output {
+structure GetAuditConfiguration_Output {
     @httpPayload
     content: AuditConfigWithReadOnly
 }
-
-structure AuditConfigWithReadOnly {
-    _readonly: AuditConfigReadOnlyList,
-    config: AuditConfig
-}
-
-list AuditConfigReadOnlyList {
-    member: String
-}
diff --git a/model/security/get_certificates/operations.smithy b/model/security/get_certificates/operations.smithy
@@ -19,7 +19,7 @@ use opensearch.openapi#vendorExtensions
 @readonly
 @suppress(["HttpUriConflict"])
 @http(method: "GET", uri: "/_plugins/_security/api/ssl/certs")
-@documentation("Returns the cluster’s security certificates.")
+@documentation("Retrieves the cluster’s security certificates.")
 operation GetCertificates {
     input: GetCertificates_Input,
     output: GetCertificates_Output