Skip to main content
search
Category

Blog

Mar 01
Love0

Open API Initiative Announces Release of the OpenAPI Spec v3 Implementer’s Draft

By Blog

About a month ago, we committed to pushing out the first Implementer’s Draft of OpenAPI Specification (OAS), and now it’s arrived! Following our official versioning scheme, this version is known as 3.0.0-rc0. This is a major step toward releasing a final version of the spec.

Until the final version is released, further development of the spec will continue in the OpenAPI.next branch. The 3.0.0-rc0 release has been tagged as a fixed reference.

Since our last blog post we’ve resolved the remaining remaining structural changes to  the spec, and we have clarified a few issues and concerns and improved the documentation. Some notable changes since then are:

  • Finalized support for URL Templating.
  • Reworked support for ‘multipart/*’ and ‘x-www-form-urlencoded’, changing how file uploads are handled, and removing the ‘file’ type and ‘formData’ parameter type.
  • Request bodies are now officially not supported for HTTP verbs where the behavior is undefined.
  • Clarified how relative URLs are handled as values.
  • Callbacks’ expression language has been reworked.
  • Examples documentation has been clarified.
  • Schema Object was updated to support ‘nullable’ for null transfer values and writeOnly properties were added as well.
  • Support for JSON Schema has been updated to version draft-wright-json-schema-00 (also known as Draft 05). Differences between the OAS implementation and JSON Schema have been clarified.
  • The Header Object was updated to follow similar standards to the Parameter Object. The Items Object was removed as a result.

At this point, the specification is “feature-complete”, meaning, we will not actively discuss adding support for existing tickets. In the next few weeks, we will close tickets that have been handled or mark them for future versions.

What’s Next?

The Implementer’s Draft marks an inflection point in the push to the third generation of the specification. As we observed with version 2.0, the spec means nothing without tooling and the tooling means nothing without the spec. This draft means that all major changes have been made, and that tooling authors are encouraged to build against it, knowing that only small changes can be expected from this point forward. And just like with version 2, this is a great opportunity to be early and bring attention to your project. It is also a meaningful way to get involved with the OpenAPI community and to help drive the spec to its released state..

This means the ball is in your court. Here is how you can help:

  • Write your own tools to add support for the spec — it is an Implementer’s Draft after all. This is the only way that we can understand how well these changes are working  and that what is pushed out is usable and can be implemented fully. Working on such a tool? Let us know by filing an issue in the OpenAPI Specification Repository!
  • Find technical issues with the spec: contradiction between sections of the spec, features that don’t make sense, use cases we hadn’t taken into account. Make sure to follow up on the threads and PRs for the topic to see if there’s existing reasoning for the current implementation.
  • Find content issues in the spec: missing periods, typos, wrong examples, poor wording and so on.

The top contributors will be given a token of appreciation from the Open API Initiative.

As before, we may end up asking for contributions or feedback on specific tickets — those would be marked as ‘help wanted‘. Keep an eye on those, and don’t be afraid to jump into the discussion.

Thank you to everyone who has contributed to this substantial step forward and onward to a final OpenAPI Specification version 3.0.0 release.

Technical Developer Community

Tony Tam
VP of Swagger Products at SmartBear Software
Jeremy Whitlock
Software Engineer at Google
Ron Ratovsky
Swagger Developer Evangelist at SmartBear Software
Darrel Miller
Software Developer at Microsoft
Marsh Gardiner
Product Manager at Google
Jason Harmon
Head of APIs at Typeform
Jan 24
Love0

A New Year, a New Specification

By Blog

It has been an exciting journey, and we’re happy to announce that the OpenAPI Specification version 3.0 is coming into view!

Image from the most recent Meeting of the Open API Initiative Technical Developer Community Meeting

Image from the most recent Meeting of the Open API Initiative Technical Developer Community Meeting

Over the past year, the Technical Developer Community (TDC) has sifted through hundreds of tickets and thousands of comments — all with the goal of synthesizing community members’ requirements and improving the 2.0 specification to serve them. We have listened, debated, agreed, and disagreed, all the while keeping the spec simple and pragmatic yet still powerful. This next major milestone will be the first Implementer Draft, and it will be released on February 28, 2017.

The Changes

Over the last few months, we’ve made announcements of the upcoming changes in the spec via a series of blog posts, talks, and of course, changes to the spec itself. Here is a brief recap of some of the more notable changes:

  • Rearranged the structure of the specification for easier and extended reusability.
  • Extended JSON Schema support to include `oneOf`, `anyOf` and `not` support.
  • Changed the structure of parameters to allow the use of schema in them.
  • Added support for Cookie parameters and eliminated dataForm parameters.
  • Body parameters were extracted to their own entity.
  • Added support for content type negotiation.
  • Introduced a new format to allow static linking between responses and future requests.
  • Simplified and enhanced security definitions of APIs.
  • Added a callback mechanism to describe WebHooks.

To help tool developers, we have also committed to semantic versioning of the spec. This means that any changes to it will trigger a version update, making it easier to manage and control.

The Implementer Draft

After so much work that has gone into the specification, it is time for developers to begin to prove its use in real-world scenarios. As such, this Implementer Draft is an important step toward a final version. As this wider audience provides feedback and any resulting issues are closed, it will bring us to final release. This, today, is a call for you to start working with the specification and to help us ensure its accomplished its goals at the highest quality.

Next Steps

This also means major changes to the specification should no longer be introduced. This does not mean that the specification is fully-ready, but we have begun focusing on cleaning up the documentation to help make the new spec more approachable.

So over the next few weeks, the TDC will concentrate on closing resolved tickets and marking tickets for future versions. We will also validate that the spec has all the information needed, including clarifications and examples where appropriate.

As a community member (yes, you!) please look for any tickets marked ‘help wanted’, which indicate that assistance is needed to help resolve an open issue. As always, do not hesitate to submit additional tickets and PRs, regardless of the release status.

Nov 18
Love0

Denver-Based Cloud Elements Latest Member to Join Open API Initiative

By Blog

The Open API Initiative is pleased to welcome Cloud Elements, a unified platform for API integration and management out of Denver Colorado as the latest company to join the OAI. Here is what our newest members had to say about the benefits of joining the OAI and why they contribute to the OpenAPI Specification.

Mark Greene, CEO of Cloud Elements

Mark Greene, CEO of Cloud Elements

Mark Geene, CEO and co-founder shares “We are thrilled to be the newest members of OAI, to join in the forces to create, evolve and promote the vendor neutral API spec. Since our early days, Cloud Elements has recognized the importance of open, machine-readable API docs and have always been committed to Swagger.”

The Cloud Elements Summer Hike Days at Matthew Winters near Red Rocks.

The Cloud Elements Summer Hike Days at Matthew Winters near Red Rocks.

Joining OAI is an integral decision to our product development strategy here at Cloud Elements, which we believe will further enhance the simplicity of our API Integration platform, and continue to reduce the burden on our customers to combine Cloud Elements with other API Management Platforms and API Gateways. Ultimately we believe that the Open API Initiative not only saves a significant amount of time for our own developers, but our customers’ developers, as well.

Building APIs to a specification is a major key to success. Rocky Madden, our Senior Platform Engineer, chimes in, “Not only has the Open API Initiative taken on the Swagger Specification, but it is stepping up it’s game with v3.0, improving how APIs can be discovered and understood by humans and machines alike. Interoperability is what OAI Is all about. It’s extremely powerful when tools and services are able to be built around the same common spec, allowing us to create robust integrations, improve how we interop with other APIs, reduce time to delivery, and so on.”

Rocky Madden, Senior Software and DevOps Engineer, Cloud Elements

Rocky Madden,
Senior Software and DevOps Engineer, Cloud Elements

Madden continues, “For us specifically, the OpenAPI  Specification has improved our own platform and helps us quickly add new Elements (endpoints) to our integration catalog. The standardization has also made it possible for us to tap into other cloud services that are also built on OAI. Our partnerships with companies like Amazon AWS will allow developers to create REST APIs which can be published into such marketplaces easily, made possible, in part, by collaborating with the Open API Initiative.”

There are a lot of companies, including ourselves, joining the movement to support the Open API Initiative. We couldn’t be more thrilled to be a part of OAI and continue to create and evolve the API Description format.

Nov 17
Love0

TDC: Documentation, explaining the 3.0 spec part 5

By Blog

With the version 3.0 of the OpenAPI Specification nearing a beta candidate, this series of posts is meant to provide insight into what is changing and how from the perspective the Technical Developer Community (TDC). Earlier posts in the series described the background and rationale behind the next evolution of the spec, some Structural Changes, Request Parameters, and Protocol and Payload.

Documentation

The huge variety of tooling that grew up around previous versions of the OpenAPI Specification suggests that those developers had access to the information necessary to build those tools. Not only should the 3.0 version continue that success, but with increased participation from the members of the TDC and community, the specification should be even more accessible, clear, and unambiguous than before.

Table of Contents

openapispec_tableofcontents
A table of contents has been added to the specification by Rob Dolin in order to provide new readers a quick overview of the document structure, and it will make it easier to access relevant parts of the specification reference. As the spec changes begin to settle down, the documentation effort will pick up momentum, and the spec will become more accessible.

Common Mark

The 2.0 specification used GitHub-Flavored Markdown (GFM) in order to provide rich text descriptions of services. Unfortunately, GFM has no formal specification itself, and some of its features work only for content hosted on GitHub. For this reason, the 3.0 draft of the OpenAPI Specification has adopted the CommonMark format, which will enable tools to be more consistent in their rendering of Markdown. CommonMark is mostly compatible with GFM, so this change has little downside or impact on existing documentation. And with the detailed specification that CommonMark brings, the increased precision will have less ambiguity and should be a boon in general.

The next post will discuss other miscellaneous outstanding issues that have been raised by the community.

—
Darrell MillerAbout The Author
Darrel Miller is a Senior Software Development Engineer on Azure API Management for Microsoft. Darrel is a member of the OpenAPI Specification Technical Developer Community. You can follow him on Twitter or on his blog Bizcoder.

Nov 14
Love0

TDC: Protocol and Payload, explaining the 3.0 spec part 4

By Blog

With the version 3.0 of the OpenAPI Specification nearing a beta candidate, this series of posts is meant to provide insight into what is changing and how from the perspective the Technical Developer Community (TDC). The first post described the background and rationale behind the next evolution of the spec, the second covered Structural Changes, and the third discussed request parameters.

Protocol and Payload

The OpenAPI Specification has had great success describing standard request/response HTTP APIs. However, many in the community have expressed an interest in describing distributed APIs beyond the simple HTTP model, such as WebSockets APIs, RPC APIs, Hypermedia APIs, and publish/subscribe APIs. After much discussion by the TDC, the goal is to extend the specification to some of these new use cases without adding significant complexity to the existing use cases.

Callbacks

Webhooks leverage HTTP in an publish/subscribe pattern, and they have become a popular pattern among API providers, including Slack, GitHub, and many other popular services. Webhooks are simple to use and fit nicely into an existing HTTP-based style of API. However, one criticism of the OpenAPI spec was that it had no way to describe an outbound HTTP request and its expected response. The new callback object makes this possible. A callback object can be attached to a subscribe operation in order to describe an outbound operation that a subscriber may expect.

Path Item Out Going

Links

Many approaches for describing hypermedia APIs have been proposed to the OpenAPI repository on GitHub. A major problem is that a static description of resources in a hypermedia API runs counter to the runtime/discovery philosophy strengths of hypermedia APIs. Nonetheless, the ability to describe static relationships between resources in an API would have some benefit. To this end, the 3.0 draft specification introduces the links object in order to describe which new resources may be accessed based on the information retrieved from an initial resource. This is not necessarily hypermedia-driven in that, the URLs to the new resources have not been embedded in the returned payload, but they are constructed based on rules defined in OpenAPI Specification. A new expression syntax has been introduced to allow information from a response to be correlated with parameters in the linked operation.

Path Item Link Object

The static description of links between resources should allow the generation of more useful documentation and client libraries that can encapsulate the process of traversing from one resource to another. This could allow client libraries that reduce the coupling between client applications and server-defined resource hierarchies.

JSON Schema

A number of requests were made to expand the subset of JSON Schema that the OpenAPI spec allows to include more complex features of JSON Schema. In the 2.0 spec process, the potential tooling complexities around code generation prompted the exclusion of anyOf and oneOf. However, many users have requested relaxing that constraint, even though it would compromise tooling support for those features. This is one of the great challenges in spec design, and it is never easy when making choices like this to know whether it is better to give people sharp tools that they could cut themselves with, or to rely on experience to say no, the burden of this responsibility is too great. While OpenAPI 2.0 took the more conservative approach, the user base has grown more experienced, so some of the restrictions are being lifted, and users will have to make smart choices.

Alternative Schemas

With the improved support for non-JSON media types, the limitations of using only JSON schema to describe payloads is becoming more untenable. TDC is currently exploring options of how to enable describing the schemas of non-JSON payloads. If this challenge can be overcome, it may become possible to remove the form parameter type completely and to enable support for protocols like gRPC that use protobuf and protobuf schema.

The next post will discuss some planned improvements to Documentation.

—
Darrell MillerAbout The Author
Darrel Miller is a Senior Software Development Engineer on Azure API Management for Microsoft. Darrel is a member of the OpenAPI Specification Technical Developer Community. You can follow him on Twitter or on his blog Bizcoder.

Close Menu