why add validation to the node rather than just throwing an error here? I'm not too familiar with this method but usually we want to default to fail as early as possible and i wonder if this violates that. did you see this done elsewhere?

The addValidation (see DESIGN_GUIDELINES) method is a lazy way to delay and make decisions about processing that cannot be determined during initialization by the constructor.

For example, in this case, we get an array-type property from props and initialize an instance variable in the constructor. However, there are cases where users want to pass nothing in props and add it later with the addEnvironmentVariable method. In that case, if we check the number of elements in the array in the constructor, it will be assumed to be zero.
Because of this case, we should use this method for lazy checking instead of early checking at the constructor.

Also, if we were to check the number of elements in the array in the addEnvironmentVariable method, it would throw an error the moment the maximum number is reached, so even if users specify 60 elements for the array, they would get a message Only 50 environment variables can be set, got 51. The addValidation method is also necessary to check exactly how many elements the user has specified for the array.

Elsewhere, I saw this in CodePipeline.

https://github.com/go-to-k/aws-cdk/blob/a21731c9b1f34525433fbee668ebb2321debf5b8/packages/aws-cdk-lib/aws-codepipeline/lib/pipeline.ts#L542

I made it a little clearer.

1a100b5

thanks for the clarification. i agree that this is the right thing to do here now

Because Environment variables are not supported for merged API. The Cfn errors:

MergedAPI (MergedAPI08D3EAD1) Operation not allowed, Merged API resources are read-only (Service: AmazonDeepdish; Status Code: 400; Error Code: BadRequestException; Request ID: ...