As the API community starts a new year, we do so with an increasingly wide choice of API description formats at our disposal. However, a development late last year promises to alter this landscape by introducing an initiative aimed at standardizing how APIs are described. In November 2015 the Open API Initiative was announced, a consortium backed by the Linux Foundation, with the express goal of “creating, evolving and promoting a vendor neutral description format”.

At the heart of this format is the Swagger specification, which was donated by SmartBear software from version 2.0 as the basis for the open specification. SmartBear describes the governance structure offered by the Open API Initiative as the “next logical step” for the Swagger specification, given its popularity in the API community. The Open API Initiative also brings overt vendor backing to Swagger (or the OpenAPI Specification, under it’s new name), with the likes of IBM and Microsoft being listed as Open API Initiative members.

The Open API Initiative has been determined a Collaborative Project by the Linux Foundation, which they describe as “harnessing the power of open source development to drive innovation at unmatched speed and scale”. It will also incorporate an open governance model implemented with a “Technical Developer Committee” that ”will maintain and evolve the specification, as well as engage users for feedback to inform development”.

Move Towards Standardization

Clearly the Open API Initiative (OAI) is an important step toward the standardization of API description, underpinned by a widely used and popular format that should give the initiative a strong foothold in establishing a wide user base. As the Linux Foundation points out: “With downloads of Swagger and Swagger tooling nearly tripling over the last year, it is considered the most popular open source framework for defining and creating RESTful APIs”. Coupled with a large and active community, overt vendor support provides added impetus to the use of Swagger and thus community uptake: there is already de facto support (SmartBear cites the example of IBM Watson and the description of the Watson API using Swagger), but formal support for Swagger from the vendors involved will ultimately result in their adoption of Swagger in vendor frameworks and utilities, making it easier for their customers to use it both as an API consumer and provider with their tooling of choice.

Better vendor support for Swagger obviously brings with it the ability for API developers and API consumers to better automate development practices: As we saw in the blog post on API Transformer, automating activities such as executing test cases against well-described APIs allows IT departments to be more proactive in how they both produce and ingest APIs. Standardization around a given API description format will give developers the ability to automatically add new specifications as they are published, generating new libraries that access a given API and performing impact analysis well in advance of a human being becoming aware the API has changed.

In the future, API changes could be detected and ingested in a completely autonomous fashion, with an organization consuming new API versions as they are published with no developer input. Naturally this kind of behaviour is not specific to use of the Swagger specification, but such practices are likely to be adopted where APIs are described using a consistent, well-known specification format that increases the likelihood of deterministic results when used to generate code or documentation. Coupled with technologies like Consul, standardization on an API description specification presents the opportunity for the concept of service discovery to reach its full potential (an example of one approach to service discovery is the work of API.guru in creating a Wikipedia of REST APIs in Swagger format). Implementing the service discovery model in a manner that allows applications to select APIs that present a “best fit” based on capability or categorization relies on a good degree of standardization, and the OpenAPI Specification could offer this to consuming applications.

Finally, the support of the Linux Foundation presents the opportunity for the OpenAPI Specification to be developed more rapidly, given the resources the Foundation can bring to bear and the status of the OAI as a Collaborative Project. Examples of other successful Collaborative Projects include CloudFoundry and the Node.js Foundation. If the Foundation can indeed drive the OAI specification forward and achieve similar success then there should be exciting developments ahead for the new OpenAPI Specification specification.

Potential Pitfalls of the Open API Initiative

Whilst the OAI is an exciting development, enthusiasm for the project should be tempered with a dose of reality. Whilst the OAI will clearly benefit the continued growth of the API economy, it will take time to prove the extent to which the large vendors involved in the consortium will attempt to exert their influence and thus how the OpenAPI Specification will evolve.

Moreover, the actual structure of the Technical Developer Committee has yet to be announced, including the processes they will use to drive development and community engagement: If the implementation of the governance charter is not approached in an open and collaborative manner, their is the potential for the committee to become embroiled in disputes over the direction of the OAI. One should look at the example of Bitcoin XT and how damaging discord can be to the development of technology when the appropriate measures do not exist within a governance process to ensure fair representation for all. However, Linux Foundation Collaborative Projects have been successful in bringing technology communities together and one would hope this will continue with the OpenAPI Specification. The OAI governance charter also specifically includes a Technical Oversight Board that should help with mediation as it will manage “conflicts, violations of procedures or guidelines and any cross-project or high-level issues that cannot be resolved in the TDC”.

SmartBear has also committed to continue expanding both the Swagger community and the supporting tooling, which includes Swagger CodeGen, UI and Editor. While this can only be beneficial to the uptake of Swagger in its new guise as the OpenAPI Specification, in the longer term the needs of the community may differ from the goals of the OAI — larger members of the consortium may wish to influence the specification for their own specific use cases. It remains to be seen whether the needs of the community and the needs of the vendors will become discordant as the growth of the OAI progresses.

Finally, there is the question of all the other API description specifications that have the support of other vendors in the economy: RAML, IO Docs, API Blueprint and OData, to name but a few. Regardless of the success of the OAI, it is unlikely that the communities and vendors that maintain, support, and champion these specifications are going to join the ranks of the OAI either immediately or in the short-term. In terms of the differences between formats, some don’t like the fact that OpenAPI Specification does “not allow for properly describing the request body payload.”

The success of the OAI will largely depend on its strategy for addressing these alternative specifications and determining how to either bring them into the fold or to ensure they are interoperable with the OAI. There is also the question of how some of the consortium members address the fact of the specifications they have supported in the past, and their own migration path to the OpenAPI Specification — Microsoft is the most pertinent example of this, given their long involvement with OData as an API description specification. Whatever the strategy, there is a need to ensure that other specifications can be incorporated in some way. Without it the primary goal of the initiative, that of creating a vendor neutral format across the API economy, is likely to be stymied from the outset as the theme of inclusion will not extend to the entire community. Moreover, other specification formats and older versions of Swagger (most pertinently version 1.2) will be around for sometime so the migration path has to be both maintainable and sustainable.

Conclusion

At first sight the Open API Initiative has the potential to be a hugely valuable development for the API economy, adding the support of many major vendors and the Linux Foundation to a very popular API description specification that the API community can support. However, there are clearly a number of factors that will dictate whether the initiate succeeds in providing a holistic description methodology that can transcend other toolsets and vendors. In our post on description-agnostic API development, we alluded to the the fact that it may be difficult to establish a unified description language for all APIs and for some members of the API community it may not be desirable at all. If the Open API Initiative can bring together both the Swagger specification and other major API description specifications into a single, interoperable framework it has the potential to offer an unparalleled approach to service description that will make the API economy an even more compelling proposition.