API Elements evolution process

[kylef]

I'm opening this issue to create a discussion around how we should handle the evolution of API Elements. I would like to involve relevant parties when introducing new element types, the discussion on how new elements may be consumed by tools like console, dredd, governance etc can bring in design considerations to the element itself. It perhaps makes sense that someone from these respective tools provide any insight during the design of new elements.

The IRCv3 Working Group and the OpenAPI have been using "draft" proposals. The feature can be introduced as a draft so that the surrounding functionality can be tested out in implementations and ratified once the feature has been successfully implemented. Perhaps this isn't the flow that all changes should make. One future propsal for API Elements is regarding deployment information that can have a large impact on other tools like such as consoles, documentation renderers and API Gateways. The current proposal at #53 can grant a lot of flexibility and may be difficult to implement. This can also be a way to ensure that we are not introducing features into API Elements that will suffer from under-adoption, we don't want to be adding features into API Elements that are not going to be used in tooling. This is one problem that I can see with some of the new OpenAPI 3.0 features, the adoption rate is relatively low with various tooling not implementing some subset of the features.

Perhaps we can prefix elements with draft- and test them out in the surrounding tooling before committing to making them final. From IRCv3, there are three types of consumers (Servers, Bouncers and Clients). Finalising a new specification can require implementation in two of each kind, for example: ircv3/ircv3-specifications#378. Perhaps following a similiar model can make sense.

TL;DR: Who should we involve in the design of new API Element features?