Spec for the new Query Role API

specification/security/_types/RoleDescriptor.ts

@@ -52,6 +52,7 @@ export class RoleDescriptor {
    * @doc_id run-as-privilege
    */
   run_as?: string[]
+  description?: string
   transient_metadata?: Dictionary<string, UserDefinedValue>
 }
 

specification/security/query_roles/QueryRolesRequest.ts

@@ -0,0 +1,68 @@
+/*
+ * Licensed to Elasticsearch B.V. under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch B.V. licenses this file to you under
+ * the Apache License, Version 2.0 (the "License"); you may
+ * not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import { RoleAggregationContainer } from './types'
+import { RequestBase } from '@_types/Base'
+import { integer } from '@_types/Numeric'
+import { Sort, SortResults } from '@_types/sort'
+
+/**
+ * Retrieves roles in a paginated manner. You can optionally filter the results with a query.
+ * @rest_spec_name security.query_role
+ * @availability stack since=8.15.0 stability=stable
+ * @availability serverless stability=stable visibility=private
+ * @cluster_privileges read_security
+ */
+export interface Request extends RequestBase {
+  body: {
+    /**
+     * A query to filter which roles to return.
+     * If the query parameter is missing, it is equivalent to a `match_all` query.
+     * The query supports a subset of query types, including `match_all`, `bool`, `term`, `terms`, `match`,
+     * `ids`, `prefix`, `wildcard`, `exists`, `range`, and `simple_query_string`.
+     * You can query the following information associated with roles: `name`, `description`, `metadata`,
+     * `applications.application`, `applications.privileges`, `applications.resources`.
+     */
+    query?: RoleQueryContainer
+    /**
+     * Starting document offset.
+     * By default, you cannot page through more than 10,000 hits using the from and size parameters.
+     * To page through more hits, use the `search_after` parameter.
+     * @server_default 0
+     */
+    from?: integer
+    /**
+     * All public fields of a role are eligible for sorting.
+     * In addition, sort can also be applied to the `_doc` field to sort by index order.
+     * @doc_id sort-search-results */
+    sort?: Sort
+    /**
+     * The number of hits to return.
+     * By default, you cannot page through more than 10,000 hits using the `from` and `size` parameters.
+     * To page through more hits, use the `search_after` parameter.
+     * @server_default 10
+     */
+    size?: integer
+    /**
+     * Search after definition
+     */
+    search_after?: SortResults
+  }
+}
+

specification/security/query_roles/QueryRolesResponse.ts

@@ -0,0 +1,39 @@
+/*
+ * Licensed to Elasticsearch B.V. under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch B.V. licenses this file to you under
+ * the Apache License, Version 2.0 (the "License"); you may
+ * not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import { integer } from '@_types/Numeric'
+import { QueryRole } from './types'
+
+export class Response {
+  body: {
+    /**
+     * The total number of roles found.
+     */
+    total: integer
+    /**
+     * The number of roles returned in the response.
+     */
+    count: integer
+    /**
+     * The list of roles.
+     */
+    roles: QueryRole[]
+  }
+}
+

specification/security/query_roles/types.ts

@@ -0,0 +1,106 @@
+/*
+ * Licensed to Elasticsearch B.V. under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch B.V. licenses this file to you under
+ * the Apache License, Version 2.0 (the "License"); you may
+ * not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import { SingleKeyDictionary } from '@spec_utils/Dictionary'
+import { Field } from '@_types/common'
+import { BoolQuery } from '@_types/query_dsl/compound'
+import { SortResults } from '@_types/sort'
+import {
+  ExistsQuery,
+  IdsQuery,
+  PrefixQuery,
+  RangeQuery,
+  TermQuery,
+  TermsQuery,
+  WildcardQuery
+} from '@_types/query_dsl/term'
+import { MatchQuery, SimpleQueryStringQuery } from '@_types/query_dsl/fulltext'
+import { MatchAllQuery } from '@_types/query_dsl/MatchAllQuery'
+import { RoleDescriptor } from '@security/_types/RoleDescriptor'
+
+/**
+ * @variants container
+ * @non_exhaustive
+ */
+export class RoleQueryContainer {
+  /**
+   * matches roles matching boolean combinations of other queries.
+   * @doc_id query-dsl-bool-query
+   */
+  bool?: BoolQuery
+  /**
+   * Returns roles that contain an indexed value for a field.
+   * @doc_id query-dsl-exists-query
+   */
+  exists?: ExistsQuery
+  /**
+   * Returns roles based on their IDs.
+   * This query uses role document IDs stored in the `_id` field.
+   * @doc_id query-dsl-ids-query
+   */
+  ids?: IdsQuery
+  /**
+   * Returns roles that match a provided text, number, date or boolean value.
+   * The provided text is analyzed before matching.
+   * @doc_id query-dsl-match-query
+   */
+  match?: SingleKeyDictionary<Field, MatchQuery>
+  /**
+   * Matches all roles, giving them all a `_score` of 1.0.
+   * @doc_id query-dsl-match-all-query
+   */
+  match_all?: MatchAllQuery
+  /**
+   * Returns roles that contain a specific prefix in a provided field.
+   * @doc_id query-dsl-prefix-query
+   */
+  prefix?: SingleKeyDictionary<Field, PrefixQuery>
+  /**
+   * Returns roles that contain terms within a provided range.
+   * @doc_id query-dsl-range-query
+   */
+  range?: SingleKeyDictionary<Field, RangeQuery>
+  /**
+   * Returns roles based on a provided query string, using a parser with a limited but fault-tolerant syntax.
+   * @doc_id query-dsl-simple-query-string-query
+   */
+  simple_query_string?: SimpleQueryStringQuery
+  /**
+   * Returns roles that contain an exact term in a provided field.
+   * To return a document, the query term must exactly match the queried field's value, including whitespace and capitalization.
+   * @doc_id query-dsl-term-query
+   */
+  term?: SingleKeyDictionary<Field, TermQuery>
+  /**
+   * Returns roles that contain one or more exact terms in a provided field.
+   * To return a document, one or more terms must exactly match a field value, including whitespace and capitalization.
+   * @doc_id query-dsl-terms-query
+   */
+  terms?: TermsQuery
+  /**
+   * Returns roles that contain terms matching a wildcard pattern.
+   * @doc_id query-dsl-wildcard-query
+   */
+  wildcard?: SingleKeyDictionary<Field, WildcardQuery>
+}
+
+export class QueryRole extends RoleDescriptor {
+  _sort?: SortResults
+}
+