docs(events-targets): add documentation of invoking AwsApi method

packages/aws-cdk-lib/aws-events-targets/README.md

@@ -15,6 +15,7 @@ Currently supported are:
   - [Start a StepFunctions state machine](#start-a-stepfunctions-state-machine)
   - [Queue a Batch job](#queue-a-batch-job)
   - [Invoke an API Gateway REST API](#invoke-an-api-gateway-rest-api)
+  - [Invoke an AWS API](#invoke-an-aws-api)
   - [Invoke an API Destination](#invoke-an-api-destination)
   - [Invoke an AppSync GraphQL API](#invoke-an-appsync-graphql-api)
   - [Put an event on an EventBridge bus](#put-an-event-on-an-eventbridge-bus)
@@ -333,6 +334,67 @@ declare const rule: events.Rule;
 rule.addTarget(new targets.ApiGatewayV2(httpApi));
 ```
 
+## Invoke an AWS API
+
+Use the `AwsApi` target to make direct AWS API calls from EventBridge rules. This is useful for invoking AWS services that don't have a dedicated EventBridge target.
+
+### Basic Usage
+
+The following example shows how to update an ECS service when a rule is triggered:
+
+```ts
+const rule = new events.Rule(this, 'Rule', {
+  schedule: events.Schedule.rate(Duration.hours(1)),
+});
+
+rule.addTarget(new targets.AwsApi({
+  service: 'ECS',
+  action: 'updateService',
+  parameters: {
+    service: 'my-service',
+    forceNewDeployment: true,
+  },
+}));
+```
+
+### IAM Permissions
+
+By default, the AwsApi target automatically creates the necessary IAM permissions based on the service and action you specify. The permission format follows the pattern: `service:Action`.
+
+For example:
+
+- `ECS` service with `updateService` action → `ecs:UpdateService` permission
+- `RDS` service with `createDBSnapshot` action → `rds:CreateDBSnapshot` permission
+
+### Custom IAM Policy
+
+In some cases, you may need to provide a custom IAM policy statement, especially when:
+
+- You need to restrict permissions to specific resources (instead of `*`)
+- The service requires additional permissions beyond the main action
+- You want more granular control over the permissions
+
+```ts
+import * as iam from 'aws-cdk-lib/aws-iam';
+import * as s3 from 'aws-cdk-lib/aws-s3';
+
+declare const rule: events.Rule;
+declare const bucket: s3.Bucket;
+
+rule.addTarget(new targets.AwsApi({
+  service: 's3',
+  action: 'GetBucketEncryption',
+  parameters: {
+    Bucket: bucket.bucketName,
+  },
+  policyStatement: new iam.PolicyStatement({
+    effect: iam.Effect.ALLOW,
+    actions: ['s3:GetEncryptionConfiguration'],
+    resources: [bucket.bucketArn],
+  }),
+}));
+```
+
 ## Invoke an API Destination
 
 Use the `targets.ApiDestination` target to trigger an external API. You need to
@@ -636,7 +698,7 @@ rule.addTarget(new targets.RedshiftQuery(workgroup.attrWorkgroupWorkgroupArn, {
 
 ## Publish to an SNS Topic
 
-Use the `SnsTopic` target to publish to an SNS Topic. 
+Use the `SnsTopic` target to publish to an SNS Topic.
 
 The code snippet below creates the scheduled event rule that publishes to an SNS Topic using a resource policy.
 
@@ -664,4 +726,4 @@ const rule = new events.Rule(this, 'Rule', {
 });
 
 rule.addTarget(new targets.SnsTopic(topic, { authorizeUsingRole: true }));
-```
+```