Category

Blog

One Last Call for Comments, so Finish Your Issue or PR

By | Blog

With this blog post, we open a two-week last call for comments period for the OpenAPI Specification v3.

As mentioned last month, the OpenAPI Specification v3 is now entering a last call for comments period. You can find the latest release candidate of the OpenAPI Specification v3 at: https://github.com/OAI/OpenAPI-Specification/releases

At its meeting on Friday, 16 June, the Technical Developer Community (TDC) confirmed the below dates:

  • 4 weeks from 22 May through 16 June: to resolve remaining pull requests
  • 2 weeks from 19 June through 30 June: Comment period ← You are here
  • 2 weeks from 3 July through 14 July: to resolve remaining comments and issues
  • 1 week from 17 July through 21 July: release window (tentative)

Whether you haven’t looked at the spec since v2.0, or keep a well-worn copy of v3.0.0-rc1 next to your keyboard, this is the single best opportunity you will have to affect the spec draft before it is released.

Here are a few ways you can offer your feedback:

The OpenAPI Specification v3 is at a “release candidate” stage.  A few areas where comments would be particularly helpful are clarity of examples and descriptions of functionality.  Suggestions of new features or large changes to existing features are welcome, but in all likelihood will be considered only for a future release.

NOTE: Members of the TDC have expressed a preference for pull requests, since it makes the intention clearer, and since all changes must eventually pass through that stage. If you’re unable to submit a PR, an issue is the next best choice.

If you’re looking to generally learn more about the OpenAPI Spec v3, check-out:

Now playing: Closing Time by Semisonic

 

Financial Services Provider Finxact Joins Open API Initiative

By | Blog

This week Finxact announced it has become an official member to the Open API Initiative. Finxact collaborates with the banking industry on an Open Banking API.

Finxact is building upon the OpenAPI Specification – OAS to develop an open banking API with its community. As a virtual core, third party services and banks’ existing systems plug into Finxact’s core processing rules engine and system of record through Finxact’s Open Banking API.

“The OAI and its growing board of members is excited to welcome Finxact to the workgroup. Finxact will be the first core banking provider to officially embrace our workgroup’s mission of openness, transparency and interoperability,” said Ole Lensmar, chairman of the OAI. “Finxact and its partners are making groundbreaking contributions that will enable banks and FinTech companies to interoperate freely and transparently using the OpenAPI Specification (OAS) as the enabler for their interactions.”

Read the full press release here.

RepreZen Joins the Open API Initiative, Announces Early OAS 3.0 Tool Support

By | Blog

The OpenAPI Specification (OAS) version 2.0, formerly known as the Swagger specification, is the current industry standard for API descriptions, supported by thousands of open source projects and all major API technology vendors. And OAS version 3.0, planned for release in July 2017, is the first major update to the specification.

OpenAPI 3.0 can describe a wider range of modern REST APIs with greater precision and detail. It offers improved component reuse, more flexible message schemas, and new API features like hyperlinks and callbacks.

RepreZen is excited to announce experimental editing support for OpenAPI 3.0 in our commercial and open source software, bringing these new capabilities right to the developer desktop. Our first implementation is based on the current draft specification, and uses the Gnostic JSON Schema for OpenAPI, contributed by Tim Burks at Google.

RepreZen Joins the Open API Initiative

We’re also proud to announce that RepreZen is now a member of the Open API Initiative, where we’ll continue to work as part of the Technical Developer Community on the OpenAPI Specification.

Working with the OpenAPI community is a gratifying experience for us, because of the great depth of knowledge and thought leadership from SmartBear, Google, Microsoft and others. They’ve kept their promise of keeping the group open and vendor-neutral. And with Swagger they’ve inherited a wealth of practical knowledge, elaborated in discussion threads on GitHub (and elsewhere), and distilled into the OpenAPI Specification itself.

For the RepreZen team, this puts the official stamp on our participation, which now dates back several years, and our support for OAS as the industry-standard API description language.

And to our customers, joining the OAI is our promise to keep OAS at the center of RepreZen’s products and open source technologies, to keep innovating and building solutions that make OpenAPI work for you.

Thoughts on the OpenAPI, Past and Future

Great software is about meeting in the middle.

If you’re an idea guy like me, you come at it from the abstract viewpoint, describing the essence of the problem and the solution, with maximum insight, and minimal implementation detail. You look for the highest-level, most expressive way to represent that in a machine-readable form, and you drill down to implementation detail, but only as far as you need to.

If you’re a pragmatist, you start with the nuts and bolts, the mechanics, and refactor your way up to a more elegant solution.  But only until the elegance stops paying for itself. Then you stop, leave the rough edges for another day, and move on.

But whichever angle you come from, it’s an ongoing process of reconciliation. Evolving the software means evolving the conceptual framework and code in parallel; and constantly, artfully, weaving them together. You work top-down and bottom-up, and you meet in the middle.

The OpenAPI Specification is a beautiful example of what just the right amount of abstraction can do. It offers a step up in expressive power, allowing developers to think in terms of resources, operations and data models — familiar concepts, gliding at a comfortable altitude just above the canopy of protocols, controllers and classes.  And you don’t have to rethink your API in high-level semantics, esoteric concepts, or religious dogma.

And with a rich ecosystem of commercial and open source tools, developers have a choice of working bottom-up, using code-first annotations, or top-down, using an API description language. Wherever you start, we can all meet in the middle with the OpenAPI Spec.

Let’s Talk APIs!

Want to get involved? Our door’s open, and we love hearing from our users.

  • Talk to us, and let us know what you think about OpenAPI, RepreZen API Studio and KaiZen Editor.

Reprezen API Studio: A Complete IDE for OpenAPI Development 

RepreZen API Studio is our flagship platform for API-first design, documentation and development.

To get started, just register for the free trial, download and install.  See the FAQ article on our support site to get started.

KaiZen OpenAPI Editor: Now on Eclipse Marketplace

KaiZen OpenAPI Editor is RepreZen’s open source, Eclipse-based editor for the industry-standard OpenAPI Specification language. This is the same full-featured editor, formerly known as SwagEdit, used by RepreZen API Studio.  KaiZen OpenAPI Editor is our core editing component for OpenAPI 2.0 and 3.0.

You can try it out today by installing from Eclipse Marketplace into Eclipse Desktop IDE, Mars.2 release or later. Once you’ve installed, see the Getting Started Guide for quick overview.   

Ted Epstein
CEO of RepreZen
Ted Epstein, CEO of RepreZen, has been helping organizations simplify, unify, and harmonize their system interfaces for over 10 years. Ted leads the architecture of RAPID-ML, the first IDL to bring the power of collaborative data modeling to REST API design. Ted is co-organizer of the API-Craft NYC Meetup and has presented at conferences including QCon, EclipseCon, API-Craft, and Data Modeling Zone.

The Open API Initiative Is Sending You a Save the Date Card

By | Blog

We’re getting close to OpenAPI Spec v3.0.0 final. If you’ve been waiting to start kicking the tires on the OpenAPI Specification (OAS) v3.0.0 (f.k.a. Swagger), now is the time to be prototyping or coding. Mark your calendar for a two-week last comment period from Monday, 19 June to Friday, 30 June, and watch for a final release in July.

On March 1st, the Open API Initiative (OAI) announced the publication of the first OpenAPI Specification v3.0.0 Implementer’s Draft. This release was tagged 3.0.0-rc0, and we had a subsequent release tagged 3.0.0-rc1 near the end of April.

At its meeting on Friday, 19 May, the Technical Developer Community (TDC) agreed to target the below timeline for release:

  • 4 weeks from 22 May through 16 June: Resolve remaining pull requests
  • 2 weeks from 19 June through 30 June: Comment period
  • 2 weeks from 3 July through 14 July: Resolve remaining comments and issues
  • 1 week from 17 July through 21 July: TENTATIVE release window

In case you’re not getting push notifications to your mobile device for every change into the OpenAPI Spec repo, here are some useful links:

As mentioned above, if you’re not already doing so, now is a great time to review the latest OpenAPI Spec v3.0.0, consider how your systems and tools can take advantage of the new functionality, and consider if anything could be improved before v3.0.0 final release.

Lastly, if you’re writing any kind of tool that uses the 3.0 draft spec in any way, please let us know by completing this very short survey, because only through implementing code against the draft spec can we gain confidence in its readiness!

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

Competitors Join OAI to Lead Convergence of API Landscape

By | Blog
With the recent addition of Mulesoft — founders of RAML; joining Apiary — founders of API Blueprint; and SmartBear — stewards of Swagger, each as  members of the Open API Initiative, Jerome Louvel of Restlet took the opportunity to revisit the history of the OAI and API Specifications.

Instead of keeping direct competition between the three efforts going on, hoping that one would win and replace the two others, a better path became necessary and possible. Being close to the main actors of this story and building tools such as Restlet Studio that support both OAS and RAML and listening to our users, I realized that the ideal would be to have Apiary and MuleSoft join the Open API Initiative and contribute step by step to the convergence, not necessarily the merging, of the three specifications. On the API testing front, there are similar standardization needs, but beside the HAR (HTTP ARchive) format, only proprietary formats are available such as Postman Collections or JMeter Scripts.

Read the full article on the Restlet blog.


 

 

Note: Restlet is a founding member of the OAI and has recently joined the RAML workgroup.

 

Jerome Louvel
CTO & VP of Products at Restlet
Jerome Louvel is the Founder, CTO and VP of Products of Restlet and an expert in REST APIs. Jerome serves on the Open API Initiative Business Governing Board

The Open API Initiative and the Linux Foundation to Produce APIStrat 17

By | Blog

The Open API Initiative along with 3scale by Red Hat and the API Evangelist are pleased to announce that APIStrat has become a Linux Foundation event.

The API Strategy & Practice Conference -taking place October 31 – November 2 in Portland, OR. – will be jointly produced by Linux Foundation Events and the Open API Initiative (OAI)

For the past seven years, APIStrat was organized by 3scale, acquired by Red Hat in June 2016, who has donated the event to The Linux Foundation. The eighth edition of the conference will bring together a variety of attendees, from the API curious to developers and IT teams, business users and executives, to discuss opportunities and challenges in the API space.

“We are pleased to see APIStrat move under The Linux Foundation and the Open API Initiative. Since its inception, the conference has aimed to provide a vendor-neutral, high-quality space for discussion of the latest API topics, and I anticipate that the new organization team will manage it superbly. Like the Open API Initiative, we share a commitment to a standard common format for API definitions and see the transition for the event as a good fit,” said Steven Willmott, co-founder of APIStrat and senior director and head of API Infrastructure, Red Hat.

“After seven events, I am very pleased to see APIStrat maturing as a conference and becoming part of the Open API Initiative (OAI). The event has long been a forum for discussion around Open API (aka Swagger), so The Linux Foundation is a natural fit for hosting the conference,” said Kin Lane, co-founder of APIStrat and the API Evangelist.

The Linux Foundation produces over 100 events worldwide where the world’s leading technologists meet, collaborate and innovate.

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

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

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.