Propose a standard for OAS operationIDs.

[toumorokoshi]

OpenAPI specifications have an "operationID" field, of which there is no prescriptive syntax.

We should try define a standard for AEPs that will serve the clients.

Context:

🤔 well, I don't know if we've actually made a decision about the operationId yet, and I think that it's usage will be very critical when we start building clients.

For now I'll remove it, and will probably do a follow-up to determine the standard around OAS operations IDs.

Originally posted by @toumorokoshi in #206 (comment)

[toumorokoshi]

The operationID is a great place to add information that could be relevant to generated clients. I think we should consider how much information we could inject into it before finalizing it.

[toumorokoshi]

@mkistler raised that operationIDs are used by tools like the openapi-generator. I tried out the generator, and it looks like the mapping looks something like a direct conversion, with delimiters such as :-., removed.

I modified aepc so that the operation IDs match the grpc RPC name, and the result in the client looks pretty good:

language	operationId	methodName
go	:archiveBook	archiveBook
go	createBook	createBook
java	:archiveBook	archiveBook
java	createBook	createBook

So at the moment I am proposing:

• {verb}{noun} for standard methods (e.g. ListBook )
• :{verb}{noun} for custom methods (e.g. :ArchiveBook)

This:

• matches the proto rpc names
• looks acceptable in generated clients
• allows proper namespacing between custom methods and standard methods (the leading colon)