Consider improving API Resource design to avoid manual dependsOn

[joeduffy]

Before creating an apigateway.Integration resource, we need to have created the apigateway.Methods associated with the target apigateway.RestApi resource. Similarly, we must have created all of those things before creating the final apigateway.Deployment resource.

Because the properties of said resources do not naturally lead to the proper dependency graph, enabling parallelism can lead to attempting to create resources out of order.

We can fix this with manual dependsOn annotations, but this is unfortunate, and it seems worth considering whether we can improve the API Gateway class design to avoid needing to do so.

[lukehoban]

We support two ways of doing this today - the raw resource way, and the swaggger body property way. The former suffers from this need for dependOn in both Terraform and Cloudformation. The latter does not (and has many other benefits).

For these specific resources, I’d be inclined not to invent a third way to orchestrate them, at least not baked in to the AWS projection.

If we had a genralized solution to mapping dependencies into strongly typed part of the resource model in a resource-specific way that we could apply to all AWS resources, that might be interesting - but it’s not clear to me that could be meaningfully better than what dependsOn provides (it’ll be nearly as easy to forget one of the dependencies if there’s a strongly-typed domain-specific property on apigateway.Integration).

[joeduffy]

I feel like we're in a reasonable place here now. We have dependsOn if you need it, and it turns out, for the most part, you don't. In our own APIs we have been careful to make the overall design imply the dataflow dependencies without need for doing this explicitly.