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]
