On April 24, 2017, the news of Mulesoft joining the Open API Initiative hit the wire. Mulesoft is the proponent of the RESTful API Modeling Language (RAML), a description format for designing APIs. Mulesoft joining the OAI signals the convergence of the software industry on the Swagger/Open API Specification (OAS). I wanted to take this opportunity to discuss a little history, and what we can expect for the future of the OAS.
How it all Started
API definitions/specifications have become an important aspect of the API lifecycle, and touch on every phase, from planning to deprecation. While WADL was the predominant description format in XML for describing RESTful services, it was not the best human usable and readable option. Enter Swagger in 2010, a machine and human readable description format that defines the API’s contact. This contract defines what data is exposed by the resources and services, and how the client should call these resources. While this idea seems simple, it had powerful implications in the multi-platform API economy where services are built in many languages, and consumed by clients across different devices. Tony Tam, the creator of Swagger, recalled the goals of the Swagger specification in a recent post on the Swagger Blog:
- To be human readable. That means the spec had to be concise, organized, and clear enough that a “normal” person could understand it.
- To be machine readable. This required structure and “rules” such that the specification itself could be interpreted to “do something useful” by a computer.
- To be thorough enough to describe everything needed to consume or produce a REST API.
With the popularity of the open source Swagger specification, other description formats were released. API Blueprint was released in 2013, with a focus on ease of usage and providing better human readable documentation. RAML was developed around the need to allow developers to better model and prototype APIs before writing code. These description formats were promoted by Apiary and Mulesoft respectively. Healthy debate ensued between practitioners and consumers alike on the best description format. Then in 2015, the Swagger specification was donated to the Open API Initiative, under Linux foundation, by SmartBear Software, in a bid to standardize the adoption and development of the format, renaming it to the OpenAPI Specification (OAS). Many industry titans are part of the group, including IBM, Microsoft, and Google. Eventually, Apiary and Mulesoft officially joined the OAI, which puts to rest the the debate on the accepted API specification —
Swagger is what the industry wanted.
What to Expect?
With so many heavyweights now joining the OAI to further develop and standardize the OAS, especially the companies behind RAML and API Blueprint, we can hope to see some innovative breakthroughs in the future of API descriptions. Here’s what I expect to see as the specification evolves.
Focus on Developer Experience
The OAS makes the life of development teams easier by keeping all the stakeholders in sync with how the API is supposed to behave. At the end of the day however, APIs are only as good as their consumption. The Swagger UI, which has been the most easiest way developers generate documentation for their OAS-based API, can always be iterated on and improved. As the specification continues to evolve I hope to see a bigger emphasis on improving the documentation capabilities of the OAS going beyond the traditional capabilities of the Swagger UI, and also generating great documentation in different formats like HTML and PDF.
Focus on Sustainability
RAML has always placed an emphasis on long term API design and sustainability. With the creators of RAML now in the OAI, I hope to see the OAS evolve to support sustainable design, allowing developers to take advantage of the programing languages that aren’t traditionally REST adherent for long term scaling. We may also see more flexible prototyping options for the contract while still allowing comprehensive RESTful design.
Focus on Innovation
All the members of the OAI are known for being heavily invested in innovation and disruption in varied fields of technology. As more opinionated companies and influencers join the OAI, there’s a good chance for healthy debates and conversations that could lead to better innovation in the API description market. The next version of the OAS already supports some great features, like linking (great for Hypermedia APIs), multiple security flows across resources, and easier request-response formats. API design and documentation tools are already making the shift to the OAS. Today, the Swagger team continues to invest in bringing the next phase of open source tooling for implementing the OAS. The popular Swagger Editor and UI have been reengineered from the ground up, merging the codes into one unified codebase, that will make it easier to work with and contribute to the open source projects. This unified experience establishes a common framework for developers and end users to design, engineer and consume APIs written in the OpenAPI Specification, and lays the groundwork for compatibility with the future OpenAPI Specification 3.0, when it is released later this year. SwaggerHub, spearheaded by the same team behind Swagger, was built keeping the needs of organizations in mind when building APIs using the OAS/Swagger specification. SwaggerHub provides a central platform your entire team to work across the lifecycle of your APIs with the OAS. It will be exciting to see how such tools evolve as well as new features get added to the OAS. Learn more about what the evolution of Swagger in a recent blog post from Tony Tom on the Swagger.io Blog: MuleSoft Joins the OpenAPI Initiative: The End of the API Spec Wars.