chore: update docs on ListIdentities (#4248)

identity/handler.go

@@ -136,8 +136,13 @@ type _ struct {
 type _ struct {
 	migrationpagination.RequestParameters
 
-	// List of ids used to filter identities.
-	// If this list is empty, then no filter will be applied.
+	// Retrieve multiple identities by their IDs.
+	//
+	// This parameter has the following limitations:
+	//
+	// - Duplicate or non-existent IDs are ignored.
+	// - The order of returned IDs may be different from the request.
+	// - This filter does not support pagination. You must implement your own pagination as the maximum number of items returned by this endpoint may not exceed a certain threshold (currently 500).
 	//
 	// required: false
 	// in: query
@@ -169,9 +174,8 @@ type _ struct {
 	// in: query
 	DeclassifyCredentials []string `json:"include_credential"`
 
-	// OrganizationID is the organization id to filter identities by.
+	// List identities that belong to a specific organization.
 	//
-	// If `ids` is set, this parameter is ignored.
 	// required: false
 	// in: query
 	OrganizationID string `json:"organization_id"`

spec/api.json

@@ -3994,7 +3994,7 @@
             "x-go-enum-desc": " ConsistencyLevelUnset  ConsistencyLevelUnset is the unset / default consistency level.\nstrong ConsistencyLevelStrong  ConsistencyLevelStrong is the strong consistency level.\neventual ConsistencyLevelEventual  ConsistencyLevelEventual is the eventual consistency level using follower read timestamps."
           },
           {
-            "description": "List of ids used to filter identities.\nIf this list is empty, then no filter will be applied.",
+            "description": "Retrieve multiple identities by their IDs.\nThe order of the IDs in the response may be different from the request.\nDuplicate or non-existent IDs are ignored.\nMax. no. of ids: 500\nThis filter does not support pagination. To retrieve more than 500\nidentities by ID, split your request into multiple calls client-side.",
             "in": "query",
             "name": "ids",
             "schema": {
@@ -4032,7 +4032,7 @@
             }
           },
           {
-            "description": "OrganizationID is the organization id to filter identities by.\n\nIf `ids` is set, this parameter is ignored.",
+            "description": "List identities that belong to a specific organization.",
             "in": "query",
             "name": "organization_id",
             "schema": {

spec/swagger.json

@@ -237,7 +237,7 @@
             "items": {
               "type": "string"
             },
-            "description": "List of ids used to filter identities.\nIf this list is empty, then no filter will be applied.",
+            "description": "Retrieve multiple identities by their IDs.\nThe order of the IDs in the response may be different from the request.\nDuplicate or non-existent IDs are ignored.\nMax. no. of ids: 500\nThis filter does not support pagination. To retrieve more than 500\nidentities by ID, split your request into multiple calls client-side.",
             "name": "ids",
             "in": "query"
           },
@@ -264,7 +264,7 @@
           },
           {
             "type": "string",
-            "description": "OrganizationID is the organization id to filter identities by.\n\nIf `ids` is set, this parameter is ignored.",
+            "description": "List identities that belong to a specific organization.",
             "name": "organization_id",
             "in": "query"
           }