Long running operation AEP is incomplete/inconsistent

[dv-stewarts]

AEP-151 - Long-running operations appears to me to be incomplete. I'll list the issues I've found with it:

1. In Guidance requests should return an HTTP response code. No protobuf equivalent is suggested.
2. In Operation representation neither the protobuf or oas schema links are valid.
3. The Operations service definition protobuf definition url yields a 404 error. I couldn't find the correct definition, and all other references in the code base are to the google version. I'm unsure which to use.
4. No Operations service OAS file is linked to and none can be found in the aep repository.
5. In Querying an operation there only seems to be a HTTP GET example. No protobuf example is provided. The Operations service in AIP provides additional methods. These methods are hinted at later in the AEP. Without any examples or schema it is impossible to know what these should look like.
6. In Parallel operations resources which do not permit multiple requests must return an HTTP response code. No protobuf equivalent is suggested. In AIP the equivalent is ABORTED.
7. Various links are broken.

[rofrankel]

Thanks for the report. Respectively:

1. There's no way to return HTTP 202 with gRPC/JSON transcoding. Maybe we should change this guidance, prioritizing consistency across stacks over locally optimal behavior. Or maybe we don't, and instead move this guidance into the OAS tab?
2. These links were written in expectation that Create the Operation common component. aep-components#8 would get merged...but instead, someone commented with helpful feedback, and it fell through the cracks and I never responded. Whoops. I'll try to find time to revisit that PR (but if anyone else wants to take it over, go ahead, especially someone with more OAS experience than I have).
3. Same as above
4. Same
5. This example works for both OAS and gRPC with JSON transcoding. I think the lack of schema will be resolved once Create the Operation common component. aep-components#8 is merged. But let me know if you think there should be an explicit gRPC example as well (not even quite sure what the gRPC equivalent would be).
6. Good point. Maybe the right gRPC status is ALREADY_EXISTS, which (per here) maps to 409?
7. Filed Some links not rendering properly site-generator#30

[dv-stewarts]

1. There's no way to return HTTP 202 with gRPC/JSON transcoding. Maybe we should change this guidance, prioritizing consistency across stacks over locally optimal behavior. Or maybe we don't, and instead move this guidance into the OAS tab?

I would move this guidance to the OAS tab.

2. These links were written in expectation that Create the Operation common component. aep-components#8 would get merged...but instead, someone commented with helpful feedback, and it fell through the cracks and I never responded. Whoops. I'll try to find time to revisit that PR (but if anyone else wants to take it over, go ahead, especially someone with more OAS experience than I have).
3. Same as above
4. Same

Understood. Personally, I would refrain from publishing AEPs until they are complete to avoid these things in the future. It's a fairly negative experience to arrive on a published site and find something like this. If I had this experience as a newcomer to AEP I would be inclined to close the tab and find an alternative to AEP.

5. This example works for both OAS and gRPC with JSON transcoding. I think the lack of schema will be resolved once Create the Operation common component. aep-components#8 is merged. But let me know if you think there should be an explicit gRPC example as well (not even quite sure what the gRPC equivalent would be).

I think completing the operations component is essential as once it is completed both the OAS and gRPC text can be reduced to "implement the get in the operations service -> link"

6. Good point. Maybe the right gRPC status is ALREADY_EXISTS, which (per here) maps to 409?

Aborted already maps to 409. I have no preference as I don't know what motivated AIP to use aborted.

7. Filed Some links not rendering properly site-generator#30
   OK. I don't think this is the new site generator though, I think these links also failed on the old site. Haven't checked to confirm.

[toumorokoshi]

Hello! we'll work on getting the components in, but wanted to address a couple of the issues:

1: see #227
6: see #228 - I think we should align with the aip guidance, since it will make migration to AEP easier for those organizations that choose to do so.

[toumorokoshi]

So I took another look at this, and found some issues, and a possible path forward. The bad news is it's not compatible with google LROs at all, and might challenge protobuf / gRPC level assumptions.

1. the existing google.longrunning.Operation use "name" to define the resource path, while we use "path". This forces us to author our own proto.
2. the existing google.longrunning.Operation error message is not compatible with the problem details RFC (https://datatracker.ietf.org/doc/html/rfc9457#name-json-schema-for-http-proble) in multiple ways - missing fields like instance, status in the HTTP world and "code" in the GRPC world, as an enum. This forces:
   a. everyone who writes an AEP compliant JSON/gRPC API will require writing custom transcoding in grpc gateway and envoy to translate these data types.
   b. we will have to normalize the protobuf error message to match problem details. I predict this will have issues with things like default error responses in gRPC service implementations.

And actually, looking at 193, it already describes aep.API.problemdetails message: https://buf.build/aep/api/docs/main:aep.api#aep.api.ProblemDetails. So perhaps we are heading in that direction already.

@rofrankel you were leading the charge on the error details as well - is Roblox starting use to problem details to return error messages, as described in the AEPs?

Assuming all this, I think the steps are:

1. fix the aep-component LRO to use the problem details message
2. figure out how we can accomplish this in the gRPC / JSON gateways (probably just a matter of using the AEP types)
3. unfortunately, support both AEP-style errors / LROs and google-style for backwards compatibility.

[toumorokoshi]

• .net implementations will do it's own transcoding, that returns back an exception that we can likely not modify.
• golang has a similar challenge

[toumorokoshi]

Enumerating leftover changes from this issue, that should be addressed:

• In Guidance requests should return an HTTP response code. No protobuf equivalent is suggested.
• fix broken link to https://github.com/aep-dev/aep-components/blob/main/schemas/api/operation.md. Should be https://aep.dev/json-schema/type/operation.json.
• There should be a reference to https://buf.build/aep/api/docs/main:aep.api, point at it to discover the operations.
• In Parallel operations resources which do not permit multiple requests must return an HTTP response code. No protobuf equivalent is suggested. In AIP the equivalent is ABORTED.