[RFC] Document CF API V3 with OpenAPI

[FloThinksPi]

Just as a side note this was already briefly discussed in the App Runtime Interfaces WG and had positive feedback that something like that is thinkable for the WG

Link for easy viewing

[Samze]

thought https://github.com/rswag/rswag would be an interesting approach, create request specs that can be used to generate open api spec. That way we get a open api doc and some verification in a single definition. However that would mean creating/updating whole bunch of requests specs.

[FloThinksPi]

I tried that before the issue with that is that we dont use native rails - e.g. we dont use active records but sequel library for the models. Rswag just worked for me when its a absolute default ruby project. But i also like to give it a shot again since i last tried it 1-2 years ago. Optimally we could use something like that but in any case writing the OpenAPI spec by hand is already an improvement from writing the HTML/MD page oneself i guess. Especially for the consumer side the format is the only thing that matters. How its produced is secondary for a CF consumer, relevant for the Working Group though.

[Samze]

From a Broadcom side we're interested in helping with this effort and maintaining an OpenAPI spec for CAPI.

[stephanme]

Another point to think about: how to continue with the existing CF client libs: cf-java-client and go-cfclient?

Do we maintain multiple client libs? The existing ones for compatibility and the potentially new ones that are (partly) generated from the OpenAPI spec.

The existing ones provide additional value on top of the pure language bindings:

• authentication support and token refresh
• pagination handling
• slicing long guid lists into chunks that fit into urls
• higher level operations (cf-java-client has an operations api but only for v2)
• integration of additional api endpoints like loggregator

This goes probably beyond this RFC. The spec clearly helps to get a language binding for the CF API from scratch which is good if no library exists yet or is hopelessly outdated. But if usable client libs exist (java, golang, also python), it becomes a longer way.

[beyhan]

I would suggest following improvements in the RFC:

• The RFC should explicitly state that the ARI WG will be impacted by this initiative and will need to invest into this effort.
• The checkpoint phase should additionally define that the OpenAPI effort should be stopped if the expected spec quality can't be implemented.
• It could include a Future Improvements section that outlines potential benefits beyond initial implementation like SDK generation which could be adopted by existing CF clients and make clear that this is out of scope for this RFC.

[FloThinksPi]

Another point to think about: how to continue with the existing CF client libs: cf-java-client and go-cfclient?

Do we maintain multiple client libs? The existing ones for compatibility and the potentially new ones that are (partly) generated from the OpenAPI spec.

The existing ones provide additional value on top of the pure language bindings:

• authentication support and token refresh
• pagination handling
• slicing long guid lists into chunks that fit into urls
• higher level operations (cf-java-client has an operations api but only for v2)
• integration of additional api endpoints like loggregator

This goes probably beyond this RFC. The spec clearly helps to get a language binding for the CF API from scratch which is good if no library exists yet or is hopelessly outdated. But if usable client libs exist (java, golang, also python), it becomes a longer way.

Yea i considerd this in the draft for the RFC but removed it since it bloats it up quite a lot. I think its good to keep that in mind as follow up of this RFC.

[FloThinksPi]

I made some adoptions and worked in @beyhan and @stephanme comments.

[stephanme]

We start the FCP with the goal to accept this RFC on the TOC meeting on 2.9.