Skip to main content
search
Category

Blog

Oct 19
Love0

Fostering Ecosystem-Driven Innovation, The OAI Welcomes SAP as a New Member

By Blog

The Open API Initiative (OAI) project is pleased to announce that SAP has joined as our newest member. The OAI community is working to establish an open source foundation for developing interoperability of APIs. SAP joins 28 current members in promoting a vendor-neutral description format. OAI is hosted by The Linux Foundation, the nonprofit advancing professional open source management for mass collaboration.

“It is a testament to the shared vision of the API community and the effectiveness of open source that Global 500 companies like SAP, IBM and Google can get together and collaborate on the OpenAPI Specification along with tool providers like SmartBear and end users like Capital One,” said Ole Lensmar, OAI project chair and CTO at SmartBear.

OAI launched in 2015 to standardize how APIs are described. The recently released OpenAPI Specification v3 defines the interfaces for RESTful APIs, describing resources and operations in a format that is easily discoverable and understandable by both machines and humans. For more information about the project and specification, visit https://www.openapis.org/.

“SAP is committed to openness and choice for our customers,” said Björn Goerke, CTO of SAP and president of SAP Cloud Platform at SAP. “SAP uses machine-readable Open API specifications for our enterprise APIs. We believe this fosters ecosystem-driven innovation on top of our SAP Cloud Platform.”

SAP continues its commitment to the open source community, having previously joined transformative Linux Foundation projects such as Cloud Foundry, Hyperledger and Node.js Foundation.

Sep 26
Love0

Three common scenarios for leveraging the OpenAPI Specification

By Blog

This article is a short preview of the forthcoming talk “Designing APIs with the OpenAPI Specification” to be delivered at Codemotion conference, Madrid, Spain on November, 24th.

We, as developers, are surrounded by powerful and amazing APIs. Just finding the time to integrate the interesting services to enhance our product could be a daunting task just because time is the scarcest resource we have as developers.

API integration is a recurrent pain for developers because frequently we feel like frustrated plumbers trying to connect pipes of different sizes and materials, forced to create custom adapters and junctions over and over again. You already know the feeling, don’t you?

We are already living in fast times where the API-economy drives much of technology innovation. Platforms like Amazon, Paypal, Stripe, Heroku, and Google Maps to cite a few, are good examples of successful platforms and products that are leaders in their respective markets, creating ecosystems around them. If you own the ecosystem, you win the game. APIs have a story to tell: good APIs – easy to consume by third-parties  – can help further adoption. We, the developers as API consumers, decide in many occasion which APIs succeed and which ones are not used anymore.

In this context of rapid innovation, API discovery, and easy integration is key for every new service on town. In this field is where the OpenAPI Spec can help the most.

OpenAPI Spec provides a solid standard for describing interoperable REST APIs based on resources and HTTP. This description is useful for two types of audiences: humans and machines.

  • Humans use the specification as a source of API documentation, examples and as a guide to try out and understand the capabilities of the API. Easy of use is the key factor here for succeed.
  • Machines use the specification for creating code able to talk the service protocol in the language of your developments. Reducing in this way the hard plumbing work described before and minimizing the cost and needs for platform specific SDKs.

In my experience, there are three major use cases for using OpenAPI Spec on your API project: legacy APIs, contact-first driven, and server-first driven. Let’s review them one by one.

1. Legacy API

The first scenario covers services and APIs that are already in production. Adding an OpenAPI document will formally capture the signature of the API in a standardized way. Therefore, consumers can use this contract as documentation to easily integrate with your API.

 

As long as you are using HTTP or HTTPS with JSON or XML encoding, it doesn’t matter what language or framework you choosed for the implementation: you have an interoperable API awaiting to be discovered by the world.

 

The best thing here that surprise many people is: you don’t have to change a single bit of your running API or service. The metadata provided by the OpenAPI Spec is a contract stored in a self-contained file (YAML or JSON) you can share offline (as a file) or publish in any web server.

Adding the contract will not change a bit of your legacy implementation, but will help developers out there to try and consume your API.

2. Contract-first driven API

To speed up developments, it is frequent to work in parallel in two teams: back-end and front-end. Both can build their stuff in parallel if they agreed to an API contract. Front-end people usually create and use mock-ups of the contract to be able to work without having to be waiting for the back-end to be ready.

OpenAPI and related tools here provide good tooling for this task. The OpenAPI contract can be edited and validated with no language or implementation assumptions (making the API really very, very interoperable).

Then, using OAS code-gen tools both teams can generate skeletons for the server-side and proxies for the frontend in any supported language or platform.

I recomend this way of working when the main functionality is clear enough to be able to design the contract up-front.

In the long-term you will maintain and evolve the contract in a planned manner. So this is the recommended approach in the long-run for a high quality API contract.

Note: a clear versioning strategy is important in order not to break old clients when a new version arrive.

3. Server-first driven API

In other type of projects, developers can decide to build their API directly on their favourite language and platform and derive the API contract later, as a direct consequence of the running implementation. This scenario is also supported by the OpenAPI Spec. An specific library for the target language is employed. Using reflection techniques and metadata to discover services, types, parameters directly inspecting the source code to automatically generate an OAS compliant spec on the fly.

This approach has some advantages:

  • Auto-generated documentation and contract.
  • Contract is always in sync with service implementation.
  • Agility in server-side development.

Major cons of the approach:

  • Be diligent when evolving the service, you could inadvertently break existing clients.
  • Derived contract could lack of simplicity or UX (if compared with a contract first). What is optimized for automation could be confusing for humans: design for humans.

NOTE: I recommend the server-first approach when the requirements and design is changing fast and your team is iterating to find the right contract design. Being not yet in production, this will alleviate breaking the clients. In any case, fully review your final API contract and refactor for a better UX before launching it.

Conclusion

OpenAPI provides an interoperable way of describing an API:

  • formally enough to be consumed by machines and
  • KISS enough to be used by developers to document and learn the API.

The three scenarios described provide flexibility to fit with different project needs. Honestly, I think this is the main feature of the OpenAPI precursor, known as Swagger, got right from the very beginning: adapting well to very different development scenarios and different project development stages.

Software engineering is still a young discipline if compared with plumbing or electrical engineering. We need standards that helps us to deal with and automate repetitive tasks. That’s why, I think whatever you are, a machine or a human, exposing APIs with the OpenAPI Spec is a good thing to have in your public API!

If you liked this post and want to know more about it, join my talk at Codemotion in Madrid at November 24th and let’s deep dive on it!

About the author

 

Pedro J. Molina

Pedro J. Molina holds a PhD. in Computer Sciences from the Technical University of Valencia. After working in different product companies related to Modeling and Code Generation he set up a startup called Metadev with focus on tooling for microservices and cloud development. Twitter: @pmolinam

Sep 06
Love0

Scale an OpenAPI based web API with Google Cloud Endpoints

By Blog

With the recent announcement of OpenAPI Specification v3, it’s the right moment to pause and think for a moment about the benefits of using an API contract to describe your Web API. With an open and freely accessible, computer-friendly format, it opens up very important perspectives around tooling, compatibility, or team collaboration, as well as foster a fruitful ecosystem.

The benefits of using an OpenAPI Specification (OAS) to describe your API

In a nutshell, the API contract is the source of truth. Whether you’re the one implementing the API backend, or you’re the consumer calling the API, there’s this central contract that each party can rely on, to be certain how the API should be looking like, what kind of endpoint to expect, what payloads will be exchanged, or which status codes are used.

With a central contract, team communication and collaboration is facilitated: I’ve seen customers where a central architecture team would define a contract, that was implemented by a third-party (an outsourcing consulting company), and the API was consumed by different teams, both internally and externally. The central contract was here to facilitate the work between those teams, to ensure the contract would be fulfilled.

In addition, having such a computer-friendly contract is really useful for tooling. Out of the contract, you can generate various useful artifacts, such as:

  • static & live mocks — that consumers can use when the API is not finalized,
  • test stubs — for facilitating integration tests,
  • server skeletons — to get started implementing the business logic of the API with a ready-made project template,
  • client SDKs — offering kits consumers can use, using various languages, to call your API more easily,
  • sandbox & live playground — a visual environment for testing and calling the API, for developers to discover how the API actually works,
  • an API portal with provisioning — a website offering the API reference documentation and allowing developers to get credentials to get access to the API,
  • static documentation — perhaps with just the API reference documentation, or a bundle of useful associated user guide, etc.

However, be careful with artifact generation. As soon as you start making some customizations to what’s been generated by tools, you might run the risk of overwriting those changes the next time you re-generate those artifacts! So beware, how customization can be done and be integrated with those generated artifacts.

Presentation on scaling an OpenAPI Spec-based web API

InfoQ recently released a video from the APIDays conference that took place in Paris last year. I talked about scaling an OpenAPI Spec-based web API using Cloud Endpoints, on the Google Cloud platform.

I spoke about the topic a few times, as web APIs is a topic I enjoy, at Nordic APIs, at APIDays, or Devoxx. But it’s great to see the video online. So let me share the slide deck along with the video:

You can also have a look at the slide deck embedded below:


In my presentation and demo, I decided to use Cloud Endpoints to manage my API, and to host the business logic of my API implementation on the Google Cloud Platform. GCP (for short) provides various “compute” solutions for your projects:

  • Google App Engine (Platform-as-a-Service): you deploy your code, and all the scaling is done transparently for you by the platform,
  • Google Container Engine (Container-as-a-Service): it’s a Kubernetes-based container orchestrator where you deploy your apps in the form of containers,
  • Google Compute Engine (Infrastructure-as-a-Service): this time, it’s full VMs, with even more control on the environment, that you deploy and scale.

In my case, I went with a containerized Ratpack implementation for my API, implemented using the Apache Groovy programming language (what else? :-). So I deployed my application on Container Engine.

I described my web API via an OpenAPI descriptor, and managed it via Cloud Endpoints. Cloud Endpoints is actually the underlying infrastructure used by Google themselves, to host all the APIs developers can use today (think Google Maps API, etc.) This architecture already serves literally hundreds of billions of requests everyday… so you can assume it’s certainly quite scalable in itself. You can manage APIs described with OpenAPI, regardless of how they were implemented (totally agnostic from the underlying implementation), and it can manage both HTTP-based JSON web APIs, as well as gRPC based ones.

There are three interesting key aspects to know about Cloud Endpoints, regardless of whether you’re using the platform for public / private / mobile / micro-services APIs:

  • Cloud Endpoints takes care of security, to control access to the API, to authenticate consumers (taking advantage of API keys, Firebase auth, Auth0, JSON Web Tokens)
  • Cloud Endpoints offers logging and monitoring capabilities of key API related metrics
  • Cloud Endpoints is super snappy and scales nicely as already mentioned (we’ll come back to this in a minute)

Cloud Endpoints actually offers an open source “sidecar” container proxy. Your containerized application will go hand in hand with the Extensible Service Proxy, and will actually be wrapped by that proxy. All the calls will actually go through that proxy before hitting your own application. Interestingly, there’s not one single proxy, but each instance of you app will have its own proxy, thus diminishing the latency between the call to the proxy and the actual code execution in your app (there’s no network hop between the two, to a somewhat distant central proxy, as the two containers are together). For the record, this proxy is based on Nginx. And that proxy container can also be run elsewhere, even on your own infrastructure.

Summary

In summary, Cloud Endpoints takes care of securing, monitoring and scaling your Web API. Developing, deploying, and managing your API on Google Cloud Platform gives you the choice: in terms of protocol with JSON / HTTP based APIs or gRPC, in terms of implementation technology as you can chose any language or framework you wish that are supported by the various compute options of the platform allow you to go from PaaS, to CaaS, or IaaS. Last but not least, this solution is open: based on open standards like OpenAPI and gRPC, or by implementing its proxy on top of Nginx.

With an open format like OpenAPI Specification to describe APIs, all the stakeholders working with APIs can collaborate together and reap the following benefits.

First of all, it’s easier for teams to work effectively together, as all the members can rely on the API description to be the truth representing what the API should look like. It’s particularly true when one team designs the contract, while another team, potentially external, implements the contract. There’s one source of truth describing the API, easing communication in the team.

Secondly, as a computer-friendly and well specified format, it’s possible to automate various tasks, like generating mocks, client libraries, server skeleton, and more. You can also use that specification to check that an implementation complies with the contract.

Lastly, with an open and freely accessible format, an ecosystem of vendors, of open source projects & developers, can collaborate together, preventing lock-in effects, allowing API developers to take advantage of tools and solutions that are compatible together via the OpenAPI Specification.

Aug 17
Love0

eBay Joins the Open API Initiative

By Blog

The partnership makes it easier for eBay developers to integrate with our RESTful public APIs and evolve their buying and selling experiences on our platforms.

For more than 20 years, eBay has been a leading marketplace, connecting shoppers to their perfect item from more than 1.1 billion listings on our platform and providing opportunities for sellers to grow their businesses. Today, I’m proud to announce our membership in the Open API Initiative (OAI). This partnership will focus on the OpenAPI Specification, making it easier and faster for eBay developers to integrate with eBay’s RESTful public APIs as we evolve the buying and selling experience on eBay. This opportunity leverages technology to make it easier for our developer ecosystem to create new eBay experiences.

The OAI is an open source project under the Linux Foundation. These software projects are independently funded and are geared toward harnessing the power of collaborative development across industries and ecosystems. OAI is the most popular open source framework for defining and creating RESTful APIs, with tens of thousands of developers using the tools.

As a member of OAI, we are continuing to tap into our developer ecosystem and grow eBay’s APIs, by expanding our developer community and encouraging building to creating a more integrated platform and shopping and selling seamless experiences on eBay. Earlier this year, we we kicked off eBay Connect with seven developer events across the world to give external developers insights into our platform and encourage their innovation. And last year, eBay Developers Program revamped our API platform with 13 new standards-based APIs.

This partnership and our new APIs make it simpler for our developers and sellers to quickly integrate with eBay and onboard all their inventory—part of our promise to deliver the most powerful commerce platform to our seller and developer partners so they can build sophisticated integrations to manage all end-to-end selling operations on eBay and easily scale their business.

Gail Frederick
eBay representative on the Business Governing Board
Gail Frederick is Senior Director of Developer Ecosystem and Services at eBay, where she strives to disrupt commerce with innovative ideas to create more powerful buying and selling experiences on eBay.
Jul 26
Love0

The OAI Announces the OpenAPI Specification 3.0.0

By Blog

The Open API Initiative (OAI), a Linux Foundation project created to advance API technology, announced the 3.0.0 release of the OpenAPI Specification. The OAI provides a foundation for developing interoperability of APIs and other technologies.

The OpenAPI Specification (OAS) v3 release is the culmination of nearly two years of collaboration among senior API developers and architects from across multiple industries, such as payment and banking, cloud computing, the Internet of Things, and vendors building API solutions. Under the auspices of the OAI, this collaboration provides a common way to unify how an industry defines and describes APIs—the services fundamental to how applications talk to each other in today’s connected world. The OpenAPI Specification defines the interfaces for RESTful APIs, describing resources and operations in a format that is easily discoverable and understandable by both machines and humans.

“The release of this third-generation format is a significant milestone for our community,” said Ole Lensmar, CTO, SmartBear Software and Chair of the OAI Board. “The updates made are entirely user and usage driven and that plays a huge role in the success of the specification. One of the most powerful things about this release is its ability to drive the full API lifecycle.”

Major improvements in the new version 3 release include support for describing callbacks, links to express relationships between operations, webhooks, enhanced examples, improved parameter descriptions, and better multipart document handling. Additional features add support for templated server URLs and semantic versioning. A detailed list is available here: OpenAPI Specification v3

“We’re excited to see growth in adoption and validation for a common OAI Specification, with nearly 4X growth in member companies over the past 18 months alone and increasing interest from governments and the healthcare and fintech sectors,” said Linux Foundation Executive Director Jim Zemlin. “Such growth validates the community’s vision to deliver an open way to share data with APIs.”

APIs have been elevated from a development technique to a driver of business, necessary for technology innovation and modernization. According to ProgrammableWeb, nearly 18,000 public APIs have been published since 2005, up nearly 1,000 in the past quarter of 2017 alone. Founded in 2015, the Open API Initiative has swelled to 27 members in the last 18 months and continues to accelerate beyond API vendors to include leaders in banking, healthcare, and governments worldwide.

Industry Support for OAI

42Crunch
“42Crunch is honoured to be part of the Open API Initiative,” said Philippe Leothaud, Chief Innovation Officer at 42Crunch. “The OpenAPI Specification is open source, platform-agnostic, vendor-agnostic and extensible. Leveraging this de-facto standard will accelerate API adoption across all industry verticals and, in particular, help the automatic consumption of APIs from applications and devices.”

Hart
“Healthcare is going through a data revolution right now with APIs at the top of the agenda,” said Mohamed Alkady, President at Hart. “By agreeing on a common API structure that allows anyone to quickly help build this future without having to re-learn a new nomenclature every time. With the release of OAS3 we are getting closer to a more well defined structure that can be more universally usable and deployable. We believe the Open API Initiative and joint technologies will lead to next-generation changes in API development and we’re excited to push this initiative forward in the healthcare space.”

IBM
“The OAI has progressed this specification relatively quickly, and the IBM Cognitive Cloud and API Economy teams are set to embrace this new, open specification”, said Todd Moore, VP of Open Technology, Digital Business Group at IBM. “By helping to establish the OAI, IBM joined with other companies who understand that robust, scalable, and secure APIs for enterprise systems form the basis of modern digital ecosystems. In addition, today’s software developers want open tooling to help them quickly and consistently create APIs to accelerate business transformation. Our clients trust IBM to help them manage their entire API management life-cycle.”

Kong (Mashape)
“Kong is the world’s most popular open source API gateway, and we’ve seen incredible growth of OpenAPI Specification usage,” said Marco Palladino, CTO and Co-founder, Kong (Mashape). “API specifications are a critical part of modern API development, publishing, and consumption workflows – and the Open API Initiative has been tirelessly advancing the industry-leading OpenAPI Specification format to its milestone 3.0.0 release. We are excited to keep contributing to the tooling ecosystem around OAS.”

Microsoft
“Microsoft congratulates the Open API Initiative and its developers on the release of version three of the OpenAPI Specification,” said Kamaljit Bath, Principal PM Manager, Azure Developer Experience. “We use OpenAPI across the company including: for description of Azure APIs and generating client libraries using the AutoRest tool, for describing over 150 services integrated with Azure LogicApps / Microsoft Flow, for customers to describe APIs they’re bringing to the Azure API Management service, and for description of APIs for which we generate documentation hosted on https://docs.microsoft.com/ and https://apidocs.microsoft.com/. We look forward to the latest release and the improvements it brings for ease of authoring, maintaining, and consuming OpenAPI descriptions.”

MuleSoft
“This new version of the OpenAPI Specification (OAS) incorporates important advances in describing APIs more fully, ” says Uri Sarid, CTO, MuleSoft. “API specifications are central to enabling robust, productive, and rapidly growing marketplaces of business capabilities. These marketplaces, in turn, are at the heart of digital transformations in enterprises, in governments, and across entire industries. OAS version 3 provides a broad format for describing APIs, RAML provides a powerful format for modeling APIs, and the API Modeling Framework leverages both to provide reusability and consistency and a universal SDK for building API tooling. We look forward to continuing to invest in these and in advancing OAI standards to create value for the API ecosystem.”

Red Hat
“Red Hat is a strong believer in Open Standards and Open Source,” said Steven Willmott, Senior Director and Head of API Management, Red Hat Inc. “The progress of the Open API Initiative and this release show what the power of community can do and we are pleased to see the industry coalescing around a strong common standard.”

SmartBear
“SmartBear is a strong supporter of open source communities, having donated the original Swagger Specification to the OAI in 2015. The evolution of the spec shows the power of bringing together collaborators across industries, to evolve the specification to meet the needs of API developers and consumers across the world in an open and transparent manner,” said Ron Ratovsky, Swagger Developer Evangelist, SmartBear. “SmartBear is committed to supporting the OAS 3.0 with our open source Swagger tools and our integrated platform, SwaggerHub.”

Tyk Technologies
“An increasing number of our customers are adopting the OpenAPI Specification as the de-facto API description format,” said Martin Buhr, CEO and Founder of Tyk Technologies. “As a leading Open Source API Management platform, Tyk is committed to open source and open standards, and we’re excited to be part of the OAS v3.0 specification launch.”

Current members of the OAI include: 42Crunch, Adobe Systems, Inc., API Evangelist, Atlassian, CA Incorporated, Capital One, Cloud Elements, Finxact, LLC, Google, Inc., Hart, IBM, Intento, Inc., ISA Research Group, Mashape Inc., Microsoft Corporation, MuleSoft, Oracle Apiary, Red Hat, RepreZen, Restlet, Inc., Salesforce, Samsung ARTIK Cloud, SmartBear Software, Software AG, StopLight, and Tyk.

OpenAPI is an evolution of the Swagger specification, which was donated by SmartBear to The Linux Foundation in 2015. To get more information about the OpenAPI Specification and learn about membership and contributions, please visit: https://www.openapis.org/

Resources:

The OpenAPI Specification v3
Follow OAI on Twitter @OpenApiSpec or join the conversation on GitHub

About the Open API Initiative
The Open API Initiative (OAI) was created by a consortium of forward-looking industry experts who recognize the immense value of standardizing on how REST APIs are described. As an open governance structure under The Linux Foundation, the OAI is focused on creating, evolving and promoting a vendor-neutral description format. Visit https://www.openapis.org/ for more information.

###

The Linux Foundation has registered trademarks and uses trademarks. For a list of trademarks of The Linux Foundation, please see its trademark usage page: https://www.linuxfoundation.org/trademark-usage. Linux is a registered trademark of Linus Torvalds.

Jun 18
Love0

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

 

Jun 09
Love0

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.

Jun 07
Love0

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.
May 25
Love0

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
May 02
Love0

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
Close Menu