feat(137): add apply AEP

[toumorokoshi]

add a new standard method to document apply / PUT.

This AEP is useful for:

• APIs that would like to offer a PUT endpoint, but has lacked guidance from the AEPs.
• APIs that would like to expose a declarative-friendly API endpoint (the integration of which is simpler than apply).

Apply can also serve as an alternative to expose a create and update endpoint.

This PR also performs a few quick fixes:

• referencing the example proto instead of hard-coding the example.
• some minor fixes on the openapi (removing empty schema)
• minor fixes on the proto (removing invalid fields like 'id')

🍱 Types of changes

What types of changes does your code introduce to AEP? Put an x in the boxes
that apply

• Enhancement
• New proposal
• Migrated from google.aip.dev
• Chore / Quick Fix

📋 Your checklist for this pull request

Please review the AEP Style and Guidance for
contributing to this repository.

General

• Basic Guidance is met.
• Ensure that your PR
  references AEPs
  correctly.
• My code has been formatted
  (usually prettier -w .)

Additional checklist for a new AEP

• A new AEP should be no more than two pages if printed out.
• Ensure that the PR is editable by maintainers.
• Ensure that File structure
  guidelines are met.
• Ensure that
  Document structure
  guidelines are met.

💝 Thank you!

[toumorokoshi]

This AEP notably does not describe behavior for unpopulated fields - this is waiting on #206 to describe the HTTP behavior, at which point Apply can follow similar guidance.

[gibson042]

What benefit does Apply provide over Create that justifies deviating from specified HTTP behavior?

[gibson042]

I don't think I've seen "Apply" used in this way before, which is why I was originally confused. But it looks good now that the request target has been cleaned up, and fills a significant gap. However, I would recommend adding text to make explicit that APIs may reject attempts to create resources via Apply (e.g. because a collection does not support client-provided paths for its children).

It's also worth referencing this new AEP from 134 (Update).

[toumorokoshi]

I don't think I've seen "Apply" used in this way before, which is why I was originally confused. But it looks good now that the request target has been cleaned up, and fills a significant gap. However, I would recommend adding text to make explicit that APIs may reject attempts to create resources via Apply (e.g. because a collection does not support client-provided paths for its children).

It's also worth referencing this new AEP from 134 (Update).

Ack! Thanks for the review and approval. Yes, I will add that caveat, and include the reference from AEP 134, before merging.

[toumorokoshi]

I don't think I've seen "Apply" used in this way before, which is why I was originally confused. But it looks good now that the request target has been cleaned up, and fills a significant gap. However, I would recommend adding text to make explicit that APIs may reject attempts to create resources via Apply (e.g. because a collection does not support client-provided paths for its children).

It's also worth referencing this new AEP from 134 (Update).

Also as a quick note - the term "apply" is borrowed from Kubernetes, which uses it to refer to their PUT requests: https://kubernetes.io/docs/reference/kubectl/generated/kubectl_apply/