OpenAPI 3 Is Here
OpenAPI 3 Is Here
The third version of the Open API Initiative's OpenAPI spec is out today! Take a look at overviews of what's changing as well as how you can contribute.
Join the DZone community and get the full member experience.Join For Free
The State of API Integration 2018: Get Cloud Elements’ report for the most comprehensive breakdown of the API integration industry’s past, present, and future.
OpenAPI fans, rejoice! After a year and a half of development, the Open API Initiative has released version 3 (technically 3.0.0) of your favorite open API spec.
The latest release of the OpenAPI Specification was developed over the course of a year and a half. Though managed by the Open API Initiative (OAI), comprised of individuals from organizations ranging from Google to Microsoft to SmartBear to Adobe, everyday programmers contributed through interactions and pull requests.
In fact, as part of an open collaboration process, most new features have largely stemmed from user requests.
Other improvements include the ability to defining multiple environments, being able to reuse models and components between multiple API definitions, and being able to describe complex data models for complex architectures.
If you haven't kept too close an eye on the specification since Version 2, then 3.0.0 is going to be particularly exciting.
Organization and Reusability
One of the main goals of this version was to make it simpler and more organized. "You can reuse more parts of it," said Ron Ratovsky, Swagger developer evangelist at SmartBear and a member of the OAI's Technical Developer Community.
The structure was overhauled with that in mind, and even from the release of the Implementer's Draft in February, the team worked on removing unneeded objects and replacing them with maps to make the spec shorter.
Another major goal was an overhaul of several parameters. "We made a lot of changes to the parameters for describing operations," Ratovsky said.
For instance, the spec is coming with a new parameter type — cookie — and is getting rid of the form data and body parameters from Version 2. Instead, those two will be folded into the new requestBody parameter, which allows you to specify media types, including allowing you to pair different content with different media types.
"You get a lot more flexibility in 3.0," Ratovsky said.
Callbacks and Linking
You can now define callbacks! Built in to support asynchronous APIs, you now have more power over your callbacks.
Another huge addition, Ratovsky said, was the addition of linking capabilities. It's important to note that this is not hypermedia, but you have static linking capabilities now. When users get a response, you can give hints them as to what they can do, whether it's through the OAI or elsewhere.
Say you want to perform an operation to get an address. "You can get a link to the operation to get the users. Based on the response, you can automate the link to get the address," Ratovksy said.
As for true hypermedia, the spec might get there someday, and this feature isn't meant to replace it, but it's still a step toward customization and better control. It provides a better way to traverse the API, and there's no extra metadata for the response.
But Wait, There's More...
Those were a few of the biggest changes coming today, but that barely scratches the surface of a more than a year of continued work.
But fear not! You can get detailed breakdowns from the OAI team on each of the following categories:
- Part 1: Background and how to get involved.
- Part 2: Structural Changes
- Part 3: Request Parameters
- Part 4: Protocol and Payload
- Part 5: Documentation
Who Should Pay Attention
Obviously, everyone who wants to work with an open API specification should be mindful of these changes, but there are certainly some developers who will benefit more than others with Version 3.
"You can see this at different levels," said OAI Chair Ole Lensmar, who is also CTO of SmartBear.
Developers who want to describe Webhooks or use links in responses should definitely keep OpenAPI in mind. Anyone who is approaching hypermedia in their APIs should also take note, and devs who incorporate OpenID or other open security mechanisms should know that they'll get support in Version 3 that wasn't there before.
At the architectural level, Lensmar said, "The spec is getting so powerful," and with its focus on reuse and simplicity, he added, "The spec can be used to drive the whole API lifecycle."
Basically, if you're building APIs and want to use a standard that isn't commercially owned, you should take a look at OpenAPI.
What Isn't in V3?
As with any project, some proposals just didn't quite make the cut. As of Version 3's release, there are still about 200 open tickets. The biggest factor that couldn't be included was the ability to support more protocols than REST. REST is undoubtedly popular, but other protocols, like RPC, don't enjoy full support under OpenAPI 3.0.0.
As for the future, the team hasn't decided on whether they'll number the next version 3.1 or 4.0. It will depend on the nature of the changes that come down the pipeline. It will also depend on the feedback from the community as a whole. Speaking of which...
The OAI Needs You
The beauty of the OAI is that people don't need to be members to contribute. "The spec has evolved in a totally open, open source nature," Lensmar said. If joining an organization isn't your thing, that's totally fine.
Whether you join or not, you can still contribute to the specification via GitHub. "We've had a lot of success with issues that people felt strongly about," Ratovsky said. "We got really interesting and long discussions."
The Technical Developer Community's job is to sift through those discussions and pick out the most useful ideas to add to the specification. Of course, the more traction an idea gets among the community, the more likely it is to be included. Ratovsky encouraged everyone to open new tickets and reply to existing ones alike.
And, of course, feel free to dive into the specification and see if it fits your needs. If it doesn't, pitch new tools and new ideas.
And if it does, then you've got your hands on an open specification for your API.
Opinions expressed by DZone contributors are their own.