Add note about the status of the legacy HTTP API.

[znewman01]

Summary

Small doc clarification about the legacy HTTP API.

Ticket Link

No ticket, but this came up in the 2022-04-19 community meeting.

Release Note

NONE

[znewman01]

CC @bobcallaway @haydentherapper

Let me know if my understanding isn't quite right; I'm happy to revise the docs.

[haydentherapper]

I think I'd like a stronger statement, something like "All features should be ported to legacy HTTP API. If there's a feature that you think would negatively impact the HTTP API, open an issue to discuss."

The new gRPC API does support calls over HTTP too.

I'd propose that we keep both APIs around through the V1 launch, and consider removing the legacy API closer to a V2 launch, unless maintenance of both is trivial.

[znewman01]

Roger. I cribbed that word-for-word, and added it in both fulcio.proto and fulcio_legacy.proto.

[haydentherapper]

Looks good! I'll let Bob do the approval for the PR, in case he had a different plan in mind for the legacy HTTP API.

[bobcallaway]

My intent in naming the v1 endpoint as "legacy" and marking all of the fields in fulcio_legacy.proto as deprecated was to actually drive the opposite outcome than what is written in this PR - that the v1 endpoint should be closed to all new feature development and all additions should be made to v2 only going forward (with appropriate exceptions made for any security-related issues).

I'm not supportive of having two functionally equivalent HTTP API endpoints with semantic differences that introduce technical debt and client confusion.

+1 to making the above intent more explicit in the code comments, as well as making explicit that all additions/changes to the v2 API need to include HTTP support so as to not make gRPC a requirement for clients.

[znewman01]

+1 to the sentiment, @bobcallaway; that's what I had initially assumed and then some confusion in that regard was what prompted this. What I found when I asked at the community meeting last week was that there was general support for maintaining both, though I'm not sure whether any of those opinions were strongly held.

I'm happy to revise but want to double check whether there's any reason to keep updating the old one? If we're ensuring that the new API works over HTTP I can't think of any.

CC @haydentherapper, do you remember who else was saying we should backport stuff?

[haydentherapper]

There was a thought that clients may want to keep the legacy API around longer, but given that the V2 endpoint supports both gRPC and HTTP, just keeping V2 should be fine. +1 to what's been said - Let's close V1 to further feature development, and encourage clients to move off V1.

[bobcallaway]

@znewman01 do you want to change this PR to update the wording or do you want me to do that in a separate PR?

[znewman01]

@znewman01 do you want to change this PR to update the wording or do you want me to do that in a separate PR?

@bobcallaway I'll do it!

[znewman01]

Just pushed; should be ready for a look.

[bobcallaway]

1 nit but the intent is clearer, thanks for revising this!

[znewman01]

1 nit but the intent is clearer, thanks for revising this!

Done

[codecov-commenter]

Codecov Report

Merging #531 (54c1dd7) into main (38798fe) will increase coverage by 1.93%.
The diff coverage is n/a.

@@            Coverage Diff             @@
##             main     #531      +/-   ##
==========================================
+ Coverage   33.75%   35.68%   +1.93%     
==========================================
  Files          18       18              
  Lines        1357     1415      +58     
==========================================
+ Hits          458      505      +47     
- Misses        836      851      +15     
+ Partials       63       59       -4     

Impacted Files	Coverage Δ
pkg/api/error.go	100.00% <0.00%> (ø)
pkg/api/client.go	0.00% <0.00%> (ø)
pkg/api/legacy_server.go	0.00% <0.00%> (ø)
pkg/api/grpc_server.go	52.97% <0.00%> (+7.24%)	⬆️
pkg/challenges/challenges.go	28.78% <0.00%> (+7.30%)	⬆️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 38798fe...54c1dd7. Read the comment docs.