Lower resource_id requirement to MUST for control plane, SHOULD for data plane

[toumorokoshi]

Based on feedback from the workspace team, the resource_id should likely be required for Control Plane resources, but optional for data plane.

To help clarify this, the data plane should be well defined in the AIPs.

[DanielvNiek]

I agree with at least this, but would argue that data plane resources may (i.s.o. should) add a resource_id as a create request field, as the most common practice is that ids are generated for data plane resources. Also in AIP-122 it states "Resource IDs may be either always set by users (required on resource creation), optionally set by users (optional on resource creation, server-generated if unset), or never set by users (not accepted at resource creation)", which indirectly contradicts the current requirement that the resource_id field must be present for all create requests.

[toumorokoshi]

I agree with at least this, but would argue that data plane resources may (i.s.o. should) add a resource_id as a create request field, as the most common practice is that ids are generated for data plane resources.

There has been a bit of internal discussion on this topic in API-design-team chat, but what is the advantage of server-generated IDs for data plane resources such that it should be the default?

Generally the exceptional cases discussed have been APIs that already use server-generated IDs, such that the API is difficult to change.

I'd argue that resources generally benefit from the ability to have a user-identifiable unique value: It enables idempotency without a separate value like AIP-155's request_id. Oftentimes idempotency is a desirable trait, at which point a client must generate it's own value regardless of whether it is in the request or the resource.

Also in AIP-122 it states "Resource IDs may be either always set by users (required on resource creation), optionally set by users (optional on resource creation, server-generated if unset), or never set by users (not accepted at resource creation)", which indirectly contradicts the current requirement that the resource_id field must be present for all create requests.

Thanks for the report, we'll fix the AIPs to be consistent.

[toumorokoshi]

Adding more thoughts as they come along:

The exceptional cases discussed internally to avoid this guidance was cases where the underlying infrastructure is difficult to change away from a server-generated ID. e.g. things like GCP organizations or projects.

It's probably worth explaining that AIP musts do not mean that one has to rectify them immediately: services can have practical constraints that make it difficult to adhere to the latest AIP guidance. For future versions of the service it would be desirable to adhere to them, but just like any software adhering to API standards is a practical exercise.

As another reason APIs have server-generated IDs: this also comes up in cases where a particular resource is uniquely identified by a value that isn't the server-generated ID, and to allow that type of change. For example, a user's account where the e-mail or even the username might change.