I actually think that should be a hard requirement for the "next" API ... if v2 is so different and awkward compared to a broadly adopted standard, I'd say that's a short-coming of the v2 design. If we're going to keep rolling out APIs that no standardized tooling supports, just stick with v1, our users are no better off.
On Fri, Oct 29, 2021 at 9:52 AM Eric Pugh <[email protected]> wrote: > > I did try to write a OpenAPI specification for V2, and discovered how much > customization/specifics I would have to do, and gave up because we were so > very different. With the “experimental” tag, we could evolve towards the > OpenAPI spec standards if folks wanted to ;-) > > On Oct 29, 2021, at 11:48 AM, Timothy Potter <[email protected]> wrote: > > Does the v2 API support OpenAPI? I looked over the docs and it seems > like not, which is a shame. OpenAPI > (https://swagger.io/specification/) opens up a mature ecosystem of > tooling. The _introspection endpoint seems nice but if automated tools > can't understand it, then our users can't auto-generate SDKs or > interact with the API using tools like SwaggerUI, and so on. > Once your API is OpenAPI compliant, you don't need to "document" it, > tools will do that for you. > > I really think adopting this standard should be part of this > conversation, otherwise, we're just re-inventing the wheel around API > design and leaving too much heavy-lifting for ourselves. > > Tim > > On Thu, Oct 28, 2021 at 11:40 AM Jan Høydahl <[email protected]> wrote: > > > +1 to experimental (java level). > In user facing docs and tutorials, we can encourage use, with just a minor > note somewhere that it may still change. > When users report bugs there will always be a workaround — use v1 until next > release.. > > Jan Høydahl > > 27. okt. 2021 kl. 23:18 skrev David Smiley <[email protected]>: > > > I agree that *very* few users use V2. Ok I do at work but it's maybe one API > endpoint so whatever. We should free ourselves from the burdensome > constraints of back-compat until V2 is sufficiently ready, whenever that is. > So I agree with labeling it experimental and we can elaborate on that is the > upgrade notes. Some APIs I think are only V2, so we can clarify that we're > not saying the underlying functionality is experimental. Not only do we > have to concern ourselves with inconveniencing some users, we have to face > the reality of our limited dev resources, and thus not make the prospect of > improvements too hard (nor on potential contributors). > > > --------------------------------------------------------------------- > To unsubscribe, e-mail: [email protected] > For additional commands, e-mail: [email protected] > > > --------------------------------------------------------------------- > To unsubscribe, e-mail: [email protected] > For additional commands, e-mail: [email protected] > > > _______________________ > Eric Pugh | Founder & CEO | OpenSource Connections, LLC | 434.466.1467 | > http://www.opensourceconnections.com | My Free/Busy > Co-Author: Apache Solr Enterprise Search Server, 3rd Ed > This e-mail and all contents, including attachments, is considered to be > Company Confidential unless explicitly stated otherwise, regardless of > whether attachments are marked as such. > --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
