OpenAPI vs. Discovery

[Gerwin Sturm]

Hi,

this is more a general question and I'm aware that you are probably not going to be able/be allowed to answer it.

One of the main selling points of Google Cloud Endpoints (at least for me), was that you can use it exactly the same way, using exactly the same libraries as any other Discovery-based Google APIs.

With Cloud Endpoints moving to OpenAPI this advantage gets lost, but it's not really a big loss since Swagger/OpenAPI comes with its own set of well-supported client libraries.

I've been wondering though if Google APIs will go the same direction, switching over to OpenAPI from Discovery, because I often use a combination of Google APIs and my own Cloud Endpoints, which would require using two different client libraries or converting the discovery docs to swagger format.

While there are already solutions for accessing Google APIs via Swagger out there, I think a lot of developers would be happy if Google offered OpenAPI specifications for their APIs in addition to the discovery docs.

Not sure how closely the Cloud Endpoints team works with the Discovery team, but maybe you can forward this suggestion to them :)

Thanks,
Gerwin

[Dan Ciruli]

Hi, Gerwin -

This is a great question (and one that I've been wrestling with). As a matter of fact, both Endpoints and the Discovery infrastructure are part of the same team, so you have come to the right place.

As you probably know, we are members of the Open API Initiative and big believers that an open specification (and the toolchains that surround it) will ultimately be the best for the industry; that's why we chose it for the new Endpoints features.

It does leave us in a bit of a conundrum with respect to our existing public APIs and the existing client libraries. One thing about the Open API spec is that it is not (yet!) as rich as the Discovery Doc, so while there are client libraries in many languages, they are not quite as full featured as our existing client libraries. So if we were to step away from the Discovery infrastructure, it may mean a step back in functionality in that client library. But it would offer consistency for anyone using the Swagger codegen toolchain on top of Open API spec.

However, what we'd really like to do is get input from users like you -- and your suggestion ("offer OpenAPI specifications in addition to the discovery docs") is a good one.

What do others on the list think? 

DC

[Mark Chilvers (US - IFS)]

I think you hit the nail on the head when you stated that the Open API spec is "not (yet!) as rich as the Discovery Doc". I think for the many users of the existing public APIs that step-back in features would be too hard to swallow. My vote would be to support both, until such time as the Open API spec matures.

Mark

Mark  J Chilvers

 

PwC | UK/WC IT - Solutions Architect
Mobile: +1 813 597 4902
Email: mark.j....@pwc.com
PricewaterhouseCoopers LLP
4040 W Boy Scout Blvd, Tampa, FL 33607
Hangout: https://plus.google.com/hangouts/_/pwc.com/mchilvers003

Think more, print less

--
You received this message because you are subscribed to the Google Groups "Google Cloud Endpoints" group.
To unsubscribe from this group and stop receiving emails from it, send an email to google-cloud-endp...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/google-cloud-endpoints/c28aab04-b331-4521-8da6-fbd6613ef19a%40googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

---

The information transmitted, including any attachments, is intended only for the person or entity to which it is addressed and may contain confidential and/or privileged material. Any review, retransmission, dissemination or other use of, or taking of any action in reliance upon, this information by persons or entities other than the intended recipient is prohibited, and all liability arising therefrom is disclaimed. If you received this in error, please contact the sender and delete the material from any computer. PricewaterhouseCoopers LLP is a Delaware limited liability partnership. This communication may come from PricewaterhouseCoopers LLP or one of its subsidiaries.

[tech...@gmail.com]

I am not aware of Discovery Doc feature - is the a comparison table between both?

A backstory - I was looking for some OpenAPI discovery convention - where to put the swagger.json file, and found this thread.

To unsubscribe from this group and stop receiving emails from it, send an email to google-cloud-endpoints+unsub...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/google-cloud-endpoints/c28aab04-b331-4521-8da6-fbd6613ef19a%40googlegroups.com.

For more options, visit https://groups.google.com/d/optout.