Key takeaways
|
The Open API Initiative is a Linux Foundation workgroup tasked with generating a vendor-neutral metadata specification describing REST APIs. The basis of the Open API is the popular Swagger Specification, created by Tony Tam (@fehguy) in 2011 and led by SmartBear Software. With SmartBear’s donation of the Swagger Specification to the Open API Initiative (OAI), the group is evolving what has become the de-facto standard API Description Format to produce a consistent and compatible format for describing APIs, allowing interoperation between tooling, systems, and runtime environments. As APIs become critical to business success, the importance of the work and cooperation by the Open API Initiative members will grow rapidly.
Deepak Nadig: Jerome Louvel spoke with you back in January 2016 soon after the donation of the Swagger Specification to the Open API Initiative. What’s happened since then?
Tony Tam: The formal group and community have been hard at work gathering and consolidating feedback for the Open API Specification 3.0, the evolution of the Swagger Specification. For newcomers to the OAI, in December 2015, SmartBear—the company behind Swagger—donated the specification to the Open API Initiative under the Linux Foundation. With a formal release targeted for 2016, there are some very exciting and forward-looking changes coming to the specification.
For the existing 2.0 specification, we’re seeing adoption continue to grow exponentially. The community is continuing to push the Swagger / Open API Specification further ahead as the de-facto standard for API Description formats.
Deepak Nadig: That’s good news, and I’m sure our readers would like to hear about the details of what is going to change in the specification. Can you give us a high-level overview of what this means for tooling providers and consumers of the current Open API / Swagger Specification?
Tony Tam: First, the 3.0 specification will be breaking from 2.0. Many tooling vendors will be able to support both 2.0 and 3.0 specifications with updated tooling, but 2.0 tooling will almost certainly not work with 3.0 specifications. We expect—and encourage a better forward compatibility across tooling implementations. We will ensure that any subsequent updates to the 3.0 specification be treated as non-breaking to earn a 3.x version number. In preparing tooling providers for this inevitability, we should have better support for tools without the need for massive updates. Better compatibility across versions is in every OpenAPI Spec user’s best interest.
Next, as with 2.0, the text documentation is the source of truth for the specification. There will be an accompanying JSON schema to validate against but it is a tool, not the source of truth. Expect major changes in the documentation structure, but the overall source of truth will continue as-is, in GitHub, as a markdown document. We’ll make sure that textual documentation is improved and easier to navigate, but in the end, it should be short, concise, and easy for humans to consume. We don’t need to publish a novel, and if we need to make it too long, we probably messed something up along the way.
Finally, before we get into the details of the spec, anyone can participate in the spec evolution. Issues are tracked and organized on GitHub. The 3.0 work is in the OpenAPI.next branch. If you’re interested in what people are asking for in the OAI, this is a great place to start. There are an incredible number of use-cases described in issues in this repository, and it serves as a giant wish-list for the OAI. Of course, not everything can be addressed, but we do use these issues to capture what people are looking for.
I am happy that the spirit of the original Swagger Specification is being carried forward with the 3.0 proposal, which should help this next version of the Spec be a solid yet incremental improvement.
Deepak Nadig: Sounds good, and given that the specification is not complete, I’m sure there are many topics still being discussed. What has already been discussed and agreed upon by the OAI technical team that you can share with our readers?
Tony Tam: Let’s start with the basics. The spec will be strict, meaning arbitrary keys are not allowed. Why is this? Well, from experience it’s very difficult to help users and tooling creators write specifications if you can’t validate against it. This makes a better experience for the user by keeping them “on track”, and give them feedback if there are syntax errors. To allow for flexibility, we’ll likely keep with the 2.0 extension model, so anything with “x-“ can be added to your definition.
Deepak Nadig: Being strict in structure has been controversial in some circles, but from a tooling provider point of view, it does make sense. OK, how about the functionality inside the specification?
Tony Tam: Of course--let’s talk about hypermedia and linking. We have added a mechanism for design-time linking between operations. This will allow traversals between operations, allowing both generated API clients and documentation to provide a more intuitive flow across operations. Request and response properties can be used for the traversals, and this will allow both forward-looking non-breaking APIs to exist with type-safe code generators and fluid user interfaces that allow for simple variable and parameter passing. It’ll be a great way to move the OAI to reap many benefits of hypermedia ideas, while keeping the consistency and toolchain that was written for Swagger.
The support for JSON Schema has been expanded to include the “anyOf”, “oneOf”, and the “not” constructs. This will help produce more flexible models and complex scenarios. Previously API operations that consumed multiple different schemas could be cumbersome or impossible to model. These composition techniques will allow for multiple different schemas and declare that the API will consume or produce different types. With the additional support of the OpenAPI Initiative and the commitment to open-source tools, we should be able to bring you fantastic tooling to support this new flexibility.
We’ve clarified the structure of the specification as well, and added a new “components” section to house reusable pieces of the definition, which frees up top-level attributes to percolate throughout the document, making a clear and obvious way to override common values. For example, security may apply to all operations but one. You can define a top-level security setting which will apply to all operations, and apply a single “empty” security definition to a single operation. That’s a lot nicer on both the consumer and the developer to avoid copying content all around the spec. And it is clear, since the overriding of the security on a single operation is explicit.
Deepak Nadig: Those are good additions, I’m sure a lot of people will appreciate them. What else do you have pending in the specification?
Tony Tam: We’ve been working with a number of folks to describe callback-style events. Considering ways to model non request/response-driven operations is critical to being a forward-looking API specification, and the advent of HTTP 2.0 and socket techniques makes this a very exciting feature. We expect that modeling of webhooks and other asyc operations will now be fully describable and documented in the 3.0 spec, which will tell a consumer how to trigger a callback-type event, and what is supported on the receiving end for successful processing of the event.
WebHooks can be tricky, but with the support we’ve been planning, a server designer can tell the consumer exactly what sort of signature they need to implement for successful handling of a WebHook, and even how the consumer can send messages back to the event producer with different response codes, so you can potentially describe the subscription, unsubscription, and retry flows, making the connections 100% automatable.
Also, looking at representations and schemas; it may be a JSON world right now, but remember when the XML world would rule forever? We do, and getting more support for different schema formats is essential for the next 5-10 years of API design. Expect to see new and flexible techniques in 3.0 for this topic. Again, we’ll ensure that the final solution is implementable and not just a modeling proof-of-concept. We want the OpenAPI spec to support the rich tooling that Swagger users have come to expect.
Finally, path templates. We are working on adding as much flexibility as possible into the definition of paths, which will likely include most of the functionality described by RFC-6570, which defines four levels of support for URI templates. While we may or may not use the exact syntax of 6570, we are looking to support the use cases that it covers.
Deepak Nadig: Any closing thoughts?
Tony Tam: Many, many more topics are being covered for the 3.0 spec. We’ve been taking input from thousands of users and are thrilled to see the adoption of the OAI / Swagger specification continue to ramp exponentially.
What are you looking for in your APIs both today and tomorrow? What’s a pain that you wish was automated? Where are the troublesome spots in your API lifecycle? Get involved in the OpenAPI Initiative and be part of the API 3.0 movement!
About the Interviewee
Tony Tam was the creator of Swagger, the leading API description format used by developers in almost every modern programming language and deployment environment to design and deliver APIs that fuel IoT, microservices and mobile applications, since it began in 2011. During the development of Swagger, Tam served as the founder and CEO of Reverb, where he led development efforts of the site's innovative word navigation system. Swagger was created in response to a need his development team expressed for a better way to describe REST APIs. After making Swagger open source, Tam was the guiding force that moved the specification forward and created a vibrant enthusiastic community around it. Tam served Wordnik, the world's biggest online English dictionary, by number of words, as VP of Engineering and then CTO, among other roles.
About the Interviewer
Deepak Nadig is Distinguished Architect at Intuit. Prior to Intuit, Deepak was Head of API Platform Engineering at PayPal, and responsible for leading and transforming PayPal APIs used internally and externally to process $100 Billions of payments. Deepak has 16+ years of experience in leading engineering and architecture organizations, in high scale online websites like eBay, as well as enterprise software companies like VeriFone and HP. Deepak is a frequent speaker at conferences and is passionate about the use of technology in transforming businesses.
