All Posts By

Open API Initiative

DevSum17: OpenAPI v3 – The Evolution of API Descriptions

By | Events | No Comments

DevSum17
Stockholm, Sweden
June 8-9, 2017


The work on OpenAPI V3 is nearing completion.  What became popular as Swagger, has evolved into a new version of the specification, under the umbrella of the Linux Foundation and supported by many of the largest tech companies.

Open V3 has many improvements and new features to help you describe your APIs.  These will allow developers to describe many HTTP APIs that previously couldn’t be described with Swagger and  result in better client libraries and better documentation.

Whether you are new to OpenAPI, or have lots of experience with Swagger, this talk will contain plenty of  information about how to use OpenAPI and it’s new capabilities.  Not only will this talk provide you with what has changed you will also get insight into why the changes were made.

Come join me, and let OpenAPI take your APIs to the next level.

Level: Intermediate

 

API Design and What’s new with Open API? (Google Cloud Next ’17)

By | Presentations | No Comments

In this video, hear what’s new with the Open API Specification (OAS) — the vendor-neutral, portable, and open specification for providing technical metadata for REST APIs as well as latest trends in API design including topics such as Hypermedia and how the evolving OAI spec influences common patterns. Not just trends – this video is filled with real world examples.

 

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

By | Blog | No Comments

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

A New Year, a New Specification

By | Blog | No Comments

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.