Skip to main content
search
Category

Blog

Apr 13
Love0

Leveraging the OpenAPI Specification in Financial Services – The Story of Plaid’s OpenAPI Journey

By Blog

Written by Kin Lane, Chief Evangelist, Postman

The complexity of providing financial services to businesses and consumers in today’s business climate is hard to overstate. APIs are a critical component in providing products and services.

Plaid, whose mission is to democratize financial services through technology,  is a company that provides APIs for developers building applications in the fintech space. Plaid’s platform allows applications to connect with users’ accounts at banks and other financial institutions. Consumers and businesses can take advantage of a wide array of Plaid-powered apps to quickly and easily transfer funds, analyze their spending, apply for loans, and more.

Based on the new OpenAPI Specification 3.1.0, Plaid built an API document which allows them to easily release updates to their client libraries (they support five: Ruby, Node, Python, Java, Go). And, they have released an OpenAPI file for auto-generating your own client libraries in your preferred programming language, making it simple for you to auto-generate your own client libraries in over 40 different languages–so you can easily build with Plaid no matter the language you use.

The Journey to OpenAPI

The OpenAPI journey at Plaid did not begin with a single person or team, but was something that grew out of multiple teams with different motivations for why they needed a single machine readable truth to exist for their banking APIs. I recently spoke with Alex Hoffer of the developer relations team at Plaid to learn more about the motivations behind why Plaid chose to use the OpenAPI Specification, but also understand a little about how they arrived where they are at. 

Plaid had recently published their OpenAPI to a GitHub repository , and I thought it was a great opportunity to reach out and talk about their adoption of the OpenAPI Specification and see if they were willing to share their story with us. They were! So thank you to the Plaid team for talking with us, and sharing the details behind how OpenAPI is being applied across API operations at the banking API platform.

Creating Better Documentation More Quickly

Like most API providers, the number one reason Plaid adopted the OpenAPI Specification (OAS) was to deliver documentation for their public API. Plaid’s documentation had been in use for quite some time now, and needed a refresh, so the developer relations team embarked on a complete rewrite, and they wanted to make sure they were able to future proof their documentation so that they could evolve it alongside their API. After researching the situation it was clear that the OpenAPI Specification (OAS) was the most effective way for describing Plaid APIs in a way that would be extensible and allow it to power the current and future state of their banking API documentation. The Plaid team moved forward with a complete reworking of their documentation, and as they were working on delivering a complete OpenAPI for the Plaid API documentation other teams were also putting OpenAPI to work powering their own corner of the Plaid platform.

Delivering Client Libraries

As the developer relations team was working on the Plaid OpenAPI document, their developer experience team was also working understanding how it could also be used to deliver client libraries for the API across multiple programming languages. The developer experience team at Plaid pushes the release of multiple SDKs for the API every two weeks, which is a manual process that takes a significant amount of work and is prone to errors, while also requiring significant expertise in each language required to deliver the best possible SDK. With all this work the developer experience team was very keen on being able to automate as much of the process as possible, but as they got to work on generating SDKs from the OpenAPI they realized that the process would demand a much more robust and complete OpenAPI to deliver all of the details needed for each of the language libraries. Ultimately it took the team five months to deliver a beta set of SDKs that met the team’s expectations, but now they have a much more streamlined approach to delivering SDKs across multiple languages, while also ensuring that the SDK release process is always in alignment with the evolution of API documentation, since they both are driven from the same machine readable truth—the Plaid OpenAPI contract.

JSON Schema Now Available

Beyond developer relations and experience at Plaid, the core services team also caught wind of the OpenAPI that was being used to power documentation and generate client SDKs. The team was interested in the centralization of a machine readable truth for the Plaid API, but were particularly interested in the JSON schema now available to describe the request and response payload for each API. There was anxiety from internal developers when it came to introducing changes to the schema that was used to power the platform, and with limited visibility into what might be a breaking change with any release, developers were left with a lot of questions. With the existence of a central set of JSON Schema definitions now available as part of the OpenAPI, internal developers could now use them to validate as part of pipelines and middleware across the Plaid platform, ensuring that ongoing changes did not update or remove any properties that might introduce errors into the APIs and downstream applications of integrations. Leveraging the central OpenAPI to help make releases more reliable and less stressful for internal developers who were moving the API platform forward with new features and capabilities—reducing friction for the Plaid platform.

Defining Extensions

With the introduction of OpenAPI into the documentation, validation, and delivery of SDKs for the Plaid APIs, there were numerous immediate benefits that the teams were able to take advantage of. However, all three teams quickly began bumping against the limitations of what the OpenAPI Specification was capable of defining. Some of these needs were unique to the way Plaid does things, but other needs resemble many of the common needs you see across other API providers. This didn’t slow the Plaid teams down, and they quickly got to work defining extensions for OpenAPI that would help them define what they needed for documentation but also the very demanding needs of generating SDKs in multiple programming languages. Most notably, they also established an x-plaid- extension that would be used to describe internal schema and capabilities that would be stripped from the OpenAPI anytime the definition would be made available to the Plaid community. This work really helped Plaid realize that the OpenAPI specification really shines when you extend and push the specification to do exactly what you need, allowing the machine readable truth for their API to effectively deliver multiple essential stops along the API lifecycle like documentation, SDK generation, and validation.

Customers Request OpenAPI Specification

The Plaid OpenAPI journey reflects what many OpenAPI adopters have experienced, or are currently experiencing. While there are many motivations for why API providers adopt OpenAPI, the need to power always up to date API documentation and SDKs in a variety of programming languages are the top two. It is a journey that usually begins with the need for providing better documentation, but then as teams realize the same OpenAPI can be used to power other stops along the API lifecycle, they really see the potential of the API specification as a single source of truth or APIs. It is great to hear the story behind why Plaid is using OpenAPI, and hopefully this story provides a look into the “known knowns” of what OpenAPI can do within Plaid, but as I was finishing my conversation with Alex Hoffer, I asked her why they had published their OpenAPI to GitHub—which ultimately was the catalyst for this conversation. She simply said that an OpenAPI was a common request from their customers so they could generate their own libraries for languages they didn’t support, but also after speaking with other leading API Providers in the space, they had mentioned they were surprised by the unique things that their community was doing with their OpenAPI, innovating beyond what internal teams could deliver. Which really gets at the most powerful reasons for providing an OpenAPI for your API community, in that it will enable entirely new approaches to putting your APIs to work, which is really why we are all doing APIs in the first place. OpenAPI is just amplifying this effect and taking things to entirely new levels.

Mar 11
Love0

OpenAPI Initiative Welcomes Level 250 as Newest Member

By Announcement, Blog

Level 250 is joining the OpenAPI Initiative! Level 250 is a consulting organization that helps companies large and small improve their Product Strategies around SaaS, APIs and Developer-focused Tools: https://www.level250.com

Level 250 is run by Emmanuel Paraskakis, who has over 20 years of far-reaching experience in Product Management in organizations ranging from early-stage startups to Fortune 500 companies. Paraskakis was VP of Product Management for two of the most important API products in the world: Apiary with API Blueprint (acquired by Oracle) and SwaggerHub (and the Swagger Open Source toolset) which uses OpenAPI.

With that extensive API and product background, we asked Paraskakis about Level 250, implementing the new OpenAPI Specification 3.1.0, and where APIs are headed. We found out about how the requirements of API builders and API consumers are converging, about major improvements in reuse that will help managing scale, helping non-humans (yes), and a lot more!

— Why did Level 250 join OpenAPI Initiative and Why Now?

I have always been involved in OpenAPI, with two previous member companies, Apiary and SmartBear and so it’s part of my background. APIs and OpenAPI are at the center of everything we do at Level 250, so I want to continue to support OpenAPI in any way I can.

What makes this even more relevant today is that OpenAPI is becoming so much more that just one Spec: it’s the place where thinking and collaboration around APIs happens, whether it’s about the original OpenAPI spec, or adjacent specs such as JSON Schema and AsyncAPI, and beyond. I think OAI is becoming a focal point where the requirements of API builders and API consumers are converging. Exciting times!

— What’s the biggest issue with implementing the OpenAPI Specification?

I think the Spec is a wonderful interchange format, a Lingua Franca that most API Tools speak, so you can for example take a document that was meant as a design and reuse it to configure your API Management or your Security tests.

But because it’s become complex, encompassing many use cases, I think it’s difficult to learn and I also think it’s hard to write, for the Design-first use case for example. There are tools that make the process easier, with syntax suggestions or even UI editors, but the underlying complexity remains.

I’d love to see a simpler language that could be written by hand, perhaps leveraging examples, during the ideation and design process, and that could then translate directly into the current Spec for interoperability.

Beyond that, I think we could work more on making modularity and composition easier and also the handling of metadata, discovery and runtime configuration of API Gateways.

— Who should use the OpenAPI Specification 3.1.0?

I think the most exciting news is the full JSON Schema compatibility and support of the latest 2020-12 draft! This allows anyone to describe data structures in more detail and enhances compatibility with external tooling.

Another huge win will be for folks that need to describe Webhooks and they’ve been requesting this for some time.

One of the changes that doesn’t seem to get talked about much is the fact that you don’t _need_ to have a top-level `paths` element, you can just describe `components` and that’s still a valid OpenAPI document. That’s a huge step forward for reuse. So anyone who has lots of OpenAPI documents and is experiencing the pain of repeating information with all the problems that attracts, should be making the jump to 3.1.

— What’s your vision for the future API stack 1-3 years out?

The main problems being encountered today on the API provider side are those of managing scale and decreasing time to market, so I think Specs and various description formats play a huge role by acting as a source of truth for how our services work. I hope to see tooling that uses declarative documents to inform the entire API-building lifecycle, from ideation and design, to building tests, creating deployments on multiple environments and setting up monitoring/analytics tools – all based on the same source of truth!

On the API consumer side, we are still sending developers to documentation that can vary in quality and completeness. Humans are great at dealing with ambiguity and hopefully they’ll reach out when they have a support question. But increasingly services are consumed and discovered by machines, so I hope to see tooling that helps non-humans discover and understand the capabilities of APIs.

OpenAPI Resources

To learn more about participate in the evolution of the OpenAPI Specification: https://www.openapis.org/participate/how-to-contribute

About the OpenAPI Initiative

The OpenAPI Initiative (OAI) was created by a consortium of forward-looking industry experts who recognize the immense value of standardizing on how 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. The OpenAPI Specification was originally based on the Swagger Specification, donated by SmartBear Software. To get involved with the OpenAPI Initiative, please visithttps://www.openapis.org

About Linux Foundation

Founded in 2000, the Linux Foundation is supported by more than 1,000 members and is the world’s leading home for collaboration on open source software, open standards, open data, and open hardware. Linux Foundation projects like Linux, Kubernetes, Node.js and more are considered critical to the development of the world’s most important infrastructure. Its development methodology leverages established best practices and addresses the needs of contributors, users and solution providers to create sustainable models for open collaboration. For more information, please visit us at linuxfoundation.org.

Mar 10
Love0

OpenAPI meets SLA

By Blog

This post is authored by Dr. Pedro J. Molina, Founder at Metadev & Member at ISA Group, University of Seville.

The Special Interest Group on SLAs inside OpenAPI is working to create an extension to define Service Level Agreements for API.

The latest work of the group was recently presented to the OpenAPI Technical Steering Committee for feedback and to ensure alignment with general policies.

The SLA4OAI working group needs your help to begin realizing these benefits in practice as an extension to the OpenAPI Specification. This post will explain what an SLA is, why it matters, and how new tooling can help solve important problems faced by all API providers today.

What is an SLA?

SLA is short for Service-Level Agreement, and it defines a set of metrics and constraints regarding service availability, quality of the service like minimal and maximal throughput, latency, quotas, rate-limits, etc.

Such constraints are applied to specific endpoints or operations (resources) inside an API.

These constraints can optionally be grouped in several plans and can have price.

Diagram showing SLA as the starting point with branches to a Plan, which decomposes to Pricing, Availability, Rate, and Quota, and a separate path to Metrics and Resource/Endpoint. The paths converge.
SLA relation to Metrics, Constraints, and Plans

The problem to solve

The API industry adopted OpenAPI to move from an informal to a formal definition of APIs that can be consumed by humans for documentation and machines for automation. 

In the same way, commercial APIs often have an SLA described in informal language published over HTML pages or PDF docs, hardly usable by machines.

Therefore, a need for a standard to help to describe SLAs is pretty clear.

Use Cases with APIs

Having a standard format to describe SLAs for APIs will enable the following Use Case scenarios, to cite a few:

  1. SLA Documentation: to describe the limits, rates, quotas and expected availability, and how they apply to different endpoints.
  2. Description of Plans and prices: explaining different usage plans and costs.
  3. Feature and Cost comparison based on (2): allowing the comparison of alternative APIs based on availability and quality features.
  4. SLA Testing tools: to check if a given limit is applied by the API as documented.
  5. SLA Measure: to check the metrics are inline with the SLA contract declared.
  6. SLA Enforcing: to implement quotas and limits as a middleware for an API.
  7. SLA compliance tracking (globally or per user): to measure the degree of real compliance of an API with the SLA respect to the theoretical one.
  8. Automatic calculation of combined SLA for composed services. Several API can be used together to create complex services. SLA properties for the composition can be derived from the expected SLA from the simple components.
  9. Easy setup of SLAs in API Middleware tools. Some Middleware tools provide features to implement SLA concepts like metrics,  limits, quotas, rate limits, etc. Having a standard & formal way to define it will simplify the initial configuration of such features.

Current Specification

After months of work the Special Interest Group (SIG) generated the consensus to create a minimal version 1.0 for people to start using and for providing feedback.

You can take a look at the complete SLA specification.

Early feedback, roadmap, and open issues

SLAs definitions have an entity per se to be described in an stand-alone document apart from your OpenAPI definitions. For example, APIs described with AsyncAPI may also benefit from SLA descriptions.

Some open design questions where we would appreciate community feedback include:

  1. What is the best way of representing SLA information? There is an open discussion about if we should extend the OpenAPI document directly or if we maintain the document apart and then use references to API operations. This can be achieved using different techniques like embedded extension, patch/merge mechanisms, overlays. All of them provide pros & cons. Therefore, we are evaluating trade-offs here.
  2. SLA definitions need to reference endpoints. REST endpoints contain a URL plus a HTTP Verb (or alternatively, can be referenced by an OperationId). AsyncAPI operations will differ for sure. A reference mechanism needs to be chosen to allow pointers to specific API operations at OpenAPI, AsyncAPI or others.
  3. Usually constraints and policies apply to a set of endpoints. Instead of enumerating all of the endpoints one by one, a mechanism based on globbing (*), or Regular expressions would be very useful to briefly describe all the endpoints affected by a given limit. OpenAPI tags were also suggested as a way to apply the limits.

Call for Implementers

Time for action has arrived!

Implementers can start building new exciting tools targeting today problems that can put in practice the usage of the extension to show its usefulness. Inside the SIG we will start also doing so very soon just to show a couple of examples of use. 

So if you are interested, please feel free to ask for details and reach out to the SIG about your plans to implement it. We plan to maintain a list of related tools using the SLA spec.

To know more

  1. Current SLA4OAI Spec
  2. Wiki and working drafts
  3. SLA-SIG Mail List
  4. SLA4AOI Presentation at TSC: slides & YouTube video
  5. Paper: The Role of Limitations and SLAs in the API Industry (ESEC/FSE ’19)

Acknowledge

Thanks to all the members taking part of the SLA SIG: Tim Burks (Google), Dave O’Neil (Apimetrics), Paul Cray (Apimetrics), Hyungjun Lim (Google), Khushan Adatiya (Google), Fran Mendez (AsyncAPI), Emmanuel Paraskakis (Independent), Phil Sturgeon (Stoplight), Nikhil Kolekar (Independent), Prithpal Bhogill (Google), Madhurranjan Mohaan (Google), Isaac Hepworth (ex-Google), Scott Ganyo (Google), Kin Lane (API Evangelist), Mike Ralphson (Independent), Jeffrey ErnstFriedman (OpenTravel Alliance), Antonio Ruiz-Cortes (ISA Group/University of Sevilla), Pedro J. Molina (Metadev & ISA Group) and Pablo Fernandez (ISA Group/University of Sevilla).

Thanks also to the TSC and OpenAPI Initiative members for encouraging us and providing the resources and feedback to make this possible.

Feb 18
Love0

OpenAPI Specification 3.1.0 Released

By Announcement, Blog

OpenAPI developer community and JSON Schema community work together to build upgrade that supports 100% compatibility with the latest draft of JSON Schema

SAN FRANCISCO – February 18, 2021 – The OpenAPI Initiative, the consortium of forward-looking industry experts focused on creating, evolving and promoting the OpenAPI Specification (OAS), a vendor-neutral, open description format for HTTP (including RESTful) APIs, announced today that the OpenAPI Specification 3.1.0 has been released. This new version now supports 100% compatibility with the latest draft (2020-12) of JSON Schema.

Along with this release, the OpenAPI Initiative has sponsored the creation of new documentation to make it easier to understand the structure of the specification and its benefits. It is available here: https://oai.github.io/Documentation/ 

The OpenAPI Specification is a broadly adopted industry standard for describing modern APIs. It defines a standard, programming language-agnostic interface description for HTTP APIs which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic. 

The OpenAPI Specification (OAS) is used by organizations worldwide including Atlassian, Bloomberg, eBay, Google, IBM, Microsoft, Oracle, Postman, SAP, SmartBear, Vonage, and many more.

“The benefits of using the OpenAPI Specification are broadly applicable, ranging from API lifecycle management, to documentation, to security, to microservices development and much, much more,” said Marsh Gardiner, Product Manager, Google, and Technical Steering Committee, OpenAPI Initiative. “Great care was taken in evolving to version 3.1.0 to ensure it is an incremental upgrade for existing users, while also making it an excellent candidate for immediate evaluation and adoption in corporate environments. We extend our heartfelt gratitude to the diverse group of contributors for all their exceptional skills and effort on our latest achievement.”

“The mismatch between OpenAPI JSON Schema-like structures and JSON Schema itself has long been a problem for users and implementers. Full alignment of OpenAPI 3.1.0 with JSON Schema draft 2020-12 will not only save users much pain, but also ushers in a new standardised approach to schema extensions,” said Ben Hutton, JSON Schema project lead. “We’ve spent the last few years (and release) making sure we can clearly hear and understand issues the community faces. With our time limited volunteer based effort, not only have we fixed many pain points and added new features, but JSON Schema vocabularies allows for standards to be defined which cater for use cases beyond validation, such as the generation of code, UI, and documentation.

On Day One of JSON Schema draft 2020-12 being released, two implementations were ready. It’s humbling to work with such an experienced and skilled team.”

While JSON Schema is still technically a “draft” specification, draft 2020-12 sets a new stable foundation on which 3rd parties can build standardised extensions. The JSON Schema team do not foresee any major changes to the approach of the extension system, like dialects and vocabularies. However, the utility may be improved as feedback is received.

JSON Schema website: https://json-schema.org 

JSON Schema Open Collective: https://opencollective.com/json-schema 

JSON Schema Twitter: https://twitter.com/jsonschema

Major Changes in OpenAPI Specification 3.1.0

  • JSON Schema vocabularies alignment
  • New top-level element for describing Webhooks that are registered and managed out of band
  • Support for identifying API licenses using the standard SPDX identifier
  • PathItems object is now optional to make it simpler to create reusable libraries of components. Reusable PathItems can be described in the components object. There is also support for describing APIs secured using client certificates.

Full OpenAPI Specification 3.1.0 release notes are available here: https://github.com/OAI/OpenAPI-Specification/releases/tag/3.1.0

A Note on Semantic Versioning

The OpenAPI Initiative had adopted semantic versioning to communicate the significance of changes in software upgrades. Semantic versioning is a popular numbering methodology where minor version updates indicate changes to software are backward compatible, whereas major updates are not. Technically, using semantic versioning with the new full alignment with JSON Schema would require this change to be denoted as 4.0.0. However, this update to OpenAPI important improvements, specifically the alignment with JSON Schema, but to force it into a major release numbering would have created a mismatch of expectations.

Special Thanks

A special callout to Henry Andrews, Phil Sturgeon, and Ben Hutton for all their work, support and patient explanations they have provided to better align JSON Schema and the OpenAPI Specification. Many thanks to Lorna Mitchell for driving the Webhooks effort, using our new proposal process. And thanks to the many, many open source developers involved worldwide.

OpenAPI Resources

To learn more about participate in the evolution of the OpenAPI Specification: https://www.openapis.org/participate/how-to-contribute

●   Become a Member

●   OpenAPI Specification Twitter

●   OpenAPI Specification GitHub – Get started immediately!

●   Share your OpenAPI Spec v3 Implementations

About the OpenAPI Initiative

The OpenAPI Initiative (OAI) was created by a consortium of forward-looking industry experts who recognize the immense value of standardizing on how 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. The OpenAPI Specification was originally based on the Swagger Specification, donated by SmartBear Software. To get involved with the OpenAPI Initiative, please visit https://www.openapis.org

About Linux Foundation

Founded in 2000, the Linux Foundation is supported by more than 1,000 members and is the world’s leading home for collaboration on open source software, open standards, open data, and open hardware. Linux Foundation projects like Linux, Kubernetes, Node.js and more are considered critical to the development of the world’s most important infrastructure. Its development methodology leverages established best practices and addresses the needs of contributors, users and solution providers to create sustainable models for open collaboration. For more information, please visit us at linuxfoundation.org.

Feb 17
Love0

OpenAPI 3.1 Confoo Pass Give-away

By Blog

Coming Soon to An API Near You – OpenAPI Specification (OAS) 3.1.0!

Do you remember the old days when seeing a trailer to an upcoming movie filled you with excitement and anticipation? Well, theaters may still be closed, but there’s no need to lose your excitement for a new release, especially one that’s three years in the making.  We suspect many of you have been sitting, fingers poised above keyboards, waiting anxiously for the release of OpenAPI 3.1.0.   

Well, the wait is over! News is starting to emerge on the new features and we’re curious which parts of OpenAPI 3.1.0 you are looking forward to the most.  Is it the JSON Schema compatibility, the new webhooks support, the improved reusability…?

How do I get a Free Pass to Confoo?

It’s simple! Send us your favorite features and briefly tell us how you plan to use it.  We will enter you in a drawing for a free pass to Confoo 2021 taking place, February 24-26th. 

To enter, tweet your suggestion with @openapispec #oas31confoo by Monday, February 22, 5 pm Eastern. The winner will be selected by a random number generator.

The conference is coming up quick (and so is the release of OpenAPI 3.1.0).  Send us your feedback. 

The OpenAPI Specification relies on developers just like you to keep it current and relevant.  Join us and make your mark on the future of API standards. New to OpenAPI? Sign up for our newsletter!

Feb 16
Love0

Migrating from OpenAPI 3.0 to 3.1.0

By Blog

This post is authored by Phil Sturgeon, product manager, Stoplight, and Chairperson, Protect Earth. If you’d like to donate to Phil’s charity of choice, please see Protect Earth which is reforesting the U.K. one field at a time.

OpenAPI v3.1 brings a lot of great new functionality and improvements, and at some point in the near future you might find yourself wanting to upgrade. If you’re ready to give it a try, let’s take a look at the changes you may, or may not, need to make in order to get onto OpenAPI v3.1.

First things first, let’s change that version number! Open up your OpenAPI JSON or YAML file, and look for this line:

openapi: 3.0.3

Change that to.

openapi: 3.1.0

If instead of `openapi: 3.0.3` you see `swagger: 2.0` then see if swagger2openapi can help you upgrade to v3.0 before continuing.

In a perfect world this would be all you need to do, but despite the minor version number, v3.1 does have some small breaking changes. This decision was not made lightly. Thankfully the scope of the breaking changes is incredibly small, limited to the Schema Object, and achieves a much greater goal: full compatibility with modern JSON Schema.

OpenAPI Schema is now valid JSON Schema

Everything inside the `schema` keyword in OpenAPI is defined by the Schema Object. This has always been loosely based on JSON Schema, and referred to as a “subset superset” because it adds some things, and removes some other things from JSON Schema. This has caused confusion for some folks in the OpenAPI community. To resolve the subset superset problem, contributors from both communities came together, and got these two specifications aligned. 

OpenAPI v3.0 was based on JSON Schema Draft 05, and JSON Schema has gone through a few drafts since then: Draft 06, Draft 07, and Draft 2019-09. Now thanks to feedback gathered from users and tooling maintainers during the v3.1.0 release candidates, one more small draft was released: Draft 2020-12. This should be the last one for a while and no major changes are planned by the JSON Schema crew, so if all goes well a final release is on the horizon, to avoid any further discrepancies. 

Supporting modern JSON Schema brings lots of handy new functionality, including being able to use items arrays for tuples, or the if/then/else keywords as an alternative to awkward nested allOf > oneOf chains some folks were using for more dynamic payloads. We don’t need to learn every new thing JSON Schema can do right now, but if we’re going to upgrade we will need to know what to change in our OpenAPI documents.

Schema Object Changes

Swap nullable for type arrays

In line with JSON Schema, the `type` keyword can now define multiple types for a schema with an array. This is useful new functionality, but has also made nullable redundant. In order to achieve the goal of letting JSON Schema tools understand OpenAPI, it was decided to remove nullable entirely instead of deprecate it. 

# OpenAPI v3.0
type: string
nullable: true


# OpenAPI v3.1
type:
- "string"
- "null"

This follows the keyword independence concept, where keywords should only add constraints, but adding one more keyword should not remove a constraint. Find and replace should solve this one rather quickly.

Tweak exclusiveMinimum and exclusiveMaximum

These two keywords used to take a boolean value, which would modify the meaning of the `minimum` and `maximum` properties. In OpenAPI v3.1 they are distinct values.

# OpenAPI v3.0
minimum: 7
exclusiveMinimum: true

# OpenAPI v3.1
exclusiveMinimum: 7

Again this one can be solved with some find and replace, and I’d wager many of you don’t even use this keyword for anything.

Use examples not example

OpenAPI has a lot of places that can have an example, or multiple examples. OpenAPI v3.0 can have `example` or `examples` at the Media Type level (requests, responses, callbacks, and webooks) but it can also have a very different type of `example` inside the Schema Object. This schema object singular example was an OpenAPI-specific keyword which is no longer necessary now as JSON Schema has `examples`.

This might need an visualisation, which I will defer to Lorna Mitchell because she made some excellent slides for her talk at APIDays Paris.

# OpenAPI v3.0
type: string
example: fedora

# OpenAPI v3.1
type: string
examples: 
 - fedora

Basically switching any `example` inside a `schema` to `examples` and adding a hyphen at the start (which is a YAML array).

This is more typing if you’re writing YAML entirely by hand instead of using a visual editor, but it’s also a feature: adding multiple examples is now a lot easier. In the past to get multiple examples for a property or schema you would have to switch the type of example being used, from a property example to a media type example, which felt like overkill. Now you can do this:

type: string
examples: 
 - fedora
 - ubuntu

Describing File Upload Payloads 

In OpenAPI v3.0, describing file uploads was signalled with a type: string and the format set to byte, binary, or base64. JSON Schema helps make this far more clear with its contentEncoding and contentMediaType keywords, which are designed for exactly this sort of use.

Uploading a binary file in a POST request? No need to even use a schema now.

# OpenAPI v3.0
requestBody:
  content:
    application/octet-stream:
      schema:
        type: string
        format: binary

# OpenAPI v3.1

# OpenAPI v3.1
requestBody:
  content:
    application/octet-stream: {}

Uploading an image with base64 encoding?

# OpenAPI v3.0
requestBody:
  content:
    image/png:
      schema:
        type: string
        format: base64

# OpenAPI v3.1
requestBody:
  content:
    image/png:
      schema:
        type: string
        contentEncoding: base64

Multipart file uploads with a binary file?

# OpenAPI v3.0
requestBody:
  content:
    multipart/form-data:
  	schema:
       type: object
       properties:
        orderId:
          type: integer
        fileName:
          type: string
          format: binary

# OpenAPI v3.1
requestBody:
  content:
    multipart/form-data:
  	schema:
       type: object
       properties:
        orderId:
          type: integer
        fileName:
          type: string
          contentMediaType: application/octet-stream

This keyword supports all encodings defined in RFC4648, including “base64” and “base64url”, as well as “quoted-printable” from RFC2045.

Declaring $schema Dialects to protect against change

That’s it for things you’ll need to change, and there’s lots of other functionality I could talk about, but one thing which will help avoid change in the future is the ability to define a $schema in your schemas. 

$schema now allowed

The $schema keyword is optional but a useful way to define exactly what JSON Schema dialect a model is written in, which could be different drafts or even custom dialects. Tools which support multiple dialects can process the files slightly differently, meaning you don’t always need to make changes to all your models when upgrading OpenAPI versions in the future.

OpenAPI is entirely compatible with JSON Schema because it is now a JSON Schema dialect, so by default any schema is using `$schema. “https://spec.openapis.org/oas/3.1/dialect/base”` dialect. If you split your schemas into other JSON/YAML files and use $ref to point to them, they could contain a different $schema and override this default.

{
   $schema: "http://json-schema.org/draft-07/schema#",
}

This makes things a lot easier for tooling maintainers, because they no longer need to try and guess what draft a schema is by looking at where it is referenced from. In the past this created impossible situations where a single schema was referenced by OAS2 and OAS3 at the same time, and might have worked for a while, until a OAS3 specific keyword was added, now everything is broken for the OAS2 usage. 

Now all models can declare their own dialect and if an OpenAPI document references a dialect that the tools do not understand how to parse, it will be immediately clear, instead of breaking after several months of usage and confusing everyone. 

Feb 16
Love0

OpenAPI Initiative Welcomes Ambassador Labs as Newest Member

By Announcement, Blog

Ambassador Labs enables application developers to ship software faster on Kubernetes. The company’s Kubernetes-native API gateway offers an open source development kit to develop, manage, and monitor microservice architectures, enabling developers to adopt a cloud-native development workflow for Kubernetes services.

“We are heavily committed to improving support for OAS in our products, so joining the OAI is a natural move for us as we align closer with the OpenAPI community,” says Richard Li, CEO of Ambassador Labs. “In the cloud-native world, standardized API definitions create a natural point of integration across independent, fast-moving teams without strong central coordination.” 

“We are excited to welcome Ambassador Labs to the OpenAPI Initiative. APIs and microservices reinforce one another, and that synergy is a key reason why it is so important to standardize how we describe APIs,” said Marsh Gardiner, Product Manager, Google Cloud, and Technical Steering Committee, OpenAPI Initiative. “We look forward to working with Ambassador Labs to evolve and promote API standards like the OpenAPI Specification.”

From Ambassador Labs:

Ambassador Labs, makers of Edge Stack, the most popular Kubernetes-native API Gateway, is proud to join the OpenAPI initiative and work with OAI to establish and evangelize the standardization on OAS for API development.  Ambassador Labs is at the forefront of focusing on the cloud-native developer experience, both through dedicated developer tooling and by providing an integrated API Developer Portal. 

Ambassador Labs takes a comprehensive view of the ways in which they support developers, which is rooted in their belief that while Kubernetes represents a significant shift in technology, it really represents an opportunity to change the way developers do work. The successful shift to “cloud-native” requires multiple factors to fall into place, including the standardization on APIs, which is key to delivering an optimal developer experience.  

Learn more about open-source Ambassador API Gateway and how Ambassador empowers cloud-native developers to create flexibility and reduce complexity at www.getambassador.io.

OpenAPI Resources

To learn more about how to participate in the evolution of the OpenAPI Specification: https://www.openapis.org/participate/how-to-contribute

About Ambassador Labs

Ambassador Labs enables developers to ship without fear. Makers of the popular open source projects for Kubernetes Ambassador Edge Stack and Telepresence, Ambassador Labs is beloved by tens of thousands of developers worldwide. Used by companies such as Microsoft, PTC, NVidia, and Ticketmaster, Ambassador Labs has teams around the world. Join our community at https://www.getambassador.io.

About the OpenAPI Initiative

The OpenAPI Initiative (OAI) was created by a consortium of forward-looking industry experts who recognize the immense value of standardizing on how 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. The OpenAPI Specification was originally based on the Swagger Specification, donated by SmartBear Software. To get involved with the OpenAPI Initiative, please visit https://www.openapis.org

About Linux Foundation 

Founded in 2000, the Linux Foundation is supported by more than 1,000 members and is the world’s leading home for collaboration on open source software, open standards, open data, and open hardware. Linux Foundation projects like Linux, Kubernetes, Node.js and more are considered critical to the development of the world’s most important infrastructure. Its development methodology leverages established best practices and addresses the needs of contributors, users and solution providers to create sustainable models for open collaboration. For more information, please visit us at linuxfoundation.org.

Feb 11
Love0

OpenAPI Welcomes New Member High School Technology Services

By Announcement, Blog

The OpenAPI Initiative, the consortium of forward-looking industry experts focused on creating, evolving, and promoting the OpenAPI Specification (OAS), a vendor-neutral, open description format for RESTful APIs, is announcing today that High School Technology Services (HSTS) has joined as a new member.

Why did HSTS join the OpenAPI Initiative? From HSTS:

Matt Zand is the president of HSTS that provides high school students and adults with coding and technology training. He also is running 3 community Meetup groups (Coding and Technology Classes, JavaScript DC and Coding Bootcamps) with 4,400 members in Washington DC metro areas. Through our live events and training services, we teach students how to build and manage API applications such as RESTful APIs and along the way we promote best practices for API design, development and maintenance. 

HSTS also collaborates with its Coding Bootcamps to offer more self-paced training related to API tools and frameworks.  Likewise, HSTS has partnered with DC Web Makers in building and implementing API solutions especially related to blockchain applications. Specifically, majority of blockchain data are stored off-the-chain where a secure and scalable open API is used for connecting and exchange data from on-the-chain network to the off-the-chain database. In short, in production of a blockchain application, developers need to design and develop several APIs, most of which fall under OpenAPIs projects. 

Through training and hands-on implementations of APIs, HSTS is planning to work on API specifications to design, prototype, and document the API lifecycle.

One of key barriers for API adoption is the lack of proper training as many small companies lack skilled professionals in planning, designing and developing their API applications. Likewise, API economy needs skilled people from all parts of the organization to collaborate. We believe with the advent of emerging technologies like blockchain and Artificial Intelligence, the well-made standardized – truly Open APIs will play a vital role in the IT operation and management of companies. Indeed, the more companies pursue automation best practices, the more they value the importance of API. As such, to achieve this, companies need to provide their IT team with latest training on design and development methods, and standards intended for APIs. This is how great APIs are built! In our journey of providing community with API training and best practices, we write and publish many hands-on guides (articles and tutorials) on our sites. To learn more about our training services, visit https://myhsts.org/

OpenAPI Resources

To learn more about how to participate in the evolution of the OpenAPI Specification: https://www.openapis.org/participate/how-to-contribute

About the OpenAPI Initiative

The OpenAPI Initiative (OAI) was created by a consortium of forward-looking industry experts who recognize the immense value of standardizing on how 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. The OpenAPI Specification was originally based on the Swagger Specification, donated by SmartBear Software. To get involved with the OpenAPI Initiative, please visit https://www.openapis.org

About Linux Foundation 

Founded in 2000, the Linux Foundation is supported by more than 1,000 members and is the world’s leading home for collaboration on open source software, open standards, open data, and open hardware. Linux Foundation projects like Linux, Kubernetes, Node.js and more are considered critical to the development of the world’s most important infrastructure. Its development methodology leverages established best practices and addresses the needs of contributors, users and solution providers to create sustainable models for open collaboration. For more information, please visit us at linuxfoundation.org.

Feb 09
Love0

Vonage Joins OpenAPI Initiative

By Announcement, Blog

Press release from Vonage

Vonage, a global leader in cloud communications helping businesses accelerate their digital transformation, announced today that it has joined the OpenAPI Initiative, a consortium of forward-looking industry experts focused on creating, evolving and promoting the OpenAPI Specification (OAS).

OAS is a vendor-neutral and open description format for RESTful API, allowing both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection.

OpenAPI is an important standard for the wider API community and is adopted by most of the API service providers that help drive the sector. As a part of its OpenAPI membership, Vonage representatives will also join the Open API Business Governance Board and Technical Steering Committee to represent the Company in the meetings that decide both the direction and the detail of the OpenAPI standard.

“At Vonage, we share OpenAPI’s philosophy that technology should be easy to use and open for all,” said Roland Selmer SVP Product Management for Vonage. “We are thrilled to join OpenAPI, a community that is critical to our developer network and that will be a tremendous resource to us as we focus on the future of our API roadmap and our commitment to accelerating the world’s ability to connect.”

With an ever-growing network of more than one million registered developers, the Vonage API Platform is fully programmable, allowing businesses to integrate Video, Voice, Chat, Messaging and Verification into their existing products, workflows and systems – with just a few lines of code and no need for onsite developers or expertise. The Vonage developer community tears down the barriers to entry so that any developer can reach a global audience from day one.

“Standards are critical for helping industries scale. The OpenAPI Specification has emerged as a useful tool for describing modern APIs. Having Vonage join the OpenAPI Initiative will help our diverse membership evolve this important standard,” said Marsh Gardiner, Marketing Group Chair at the OpenAPI Initiative and Product Manager at Google Cloud.

Built using Vonage APIs, the Vonage Communications Platform provides next generation communications that are more flexible, intelligent and personal, empowering businesses to do what is next and stay ahead.

About Vonage 

Vonage, (Nasdaq:VG) a global cloud communications leader, helps businesses accelerate their digital transformation. Vonage’s Communications Platform is fully programmable and allows for the integration of Video, Voice, Chat, Messaging and Verification into existing products, workflows and systems. Vonage’s fully programmable unified communications and contact center applications are built from the Vonage platform and enable companies to transform how they communicate and operate from the office or anywhere, providing enormous flexibility and ensuring business continuity.

Vonage Holdings Corp. is headquartered in New Jersey, with offices throughout the United States, Europe, Israel, Australia and Asia. To follow Vonage on Twitter, please visit twitter.com/vonage. To become a fan on Facebook, go to facebook.com/vonage. To subscribe on YouTube, visit youtube.com/vonage.

About the OpenAPI Initiative
The OpenAPI Initiative (OAI) was created by a consortium of forward-looking industry experts who recognize the immense value of standardizing on how 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. The OpenAPI Specification was originally based on the Swagger Specification, donated by SmartBear Software. To get involved with the OpenAPI Initiative, please visit https://www.openapis.org.

Dec 15
Love0

From APIDays Paris: OpenAPI 3.1 Coming Soon

By Blog

Originally posted in the LORNAJANE Blog – Thank you, Lorna!

What’s New in OpenAPI 3.1

With OpenAPI 3.1 coming “soon”, I gave a talk at APIDays Paris about what to expect. But I’m a great fan of the written word as reference so here’s a written recap of what’s in the next OpenAPI release.

Top features:
– Compatible with JSON Schema 2020-12
– Webhook support
– Many other minor improvements

Version Numbering

As of OpenAPI 3.1, the OpenAPI project doesn’t follow semantic versioning. That sounds like a totally irresponsible decision but it actually makes some sense for a standard where every API description clearly states the version of OpenAPI it relates to. Also, they don’t let me make the rules, sadly! It’s not a major release, but some things had to be undone and redone to accommodate JSON Schema.

JSON Schema 2020-12

This is really big news, so much of OpenAPI is used alongside JSON Schema and the 3.0 release was quite a long time ago and didn’t quite accommodate everything that makes sense today in JSON Schema. This post won’t cover what’s new in JSON Schema itself but I’ll try to round up the main points from the perspective of OpenAPI users.

First of all: types can now be arrays of types, so something could be of type [string,number]. The available types also include null, so more common will be [string, ‘null’]. This does impact on existing OpenAPI documents as from 3.1, the nullable keyword is removed – use the array of types and one of the types is null.

parameters:
  - name: friendly-label
    in: query
    schema:
      type:
        - string
        - 'null'

OpenAPI 3.1 is getting support for the examples keyword within a schema, allowing an array of examples. Often the array only contains one element though. The original singular example keyword is still valid, but examples is recommended and if both are present then examples is preferred. Be aware that this array of values is in contrast with the other use of examples in OpenAPI, in a MediaType content object, where the examples field is a map with string keys. Confused? So are we. There is a post all about OpenAPI examples from Phil that explains it all!

A couple of other things are coming in from JSON Schema into the OpenAPI schemas. First of all: arbitrary keys are allowed in a schema; OpenAPI has relaxed its constraints on which fields can appear where to accommodate JSON Schema format objects. Also it’s possible to $ref to an object, then put keys alongside it which are considered in addition to what is defined in the component.

content:
  'application/json':
    schema:
      $ref: '#/components/schemas/style'
      required:
        - hue

None of these changes are huge, but having the ability to use JSON Schema within OpenAPI is brilliant for anyone wanting to use the two together so to have this commitment to supporting the ever-improving JSON Schema is excellent news.

Webhooks

I’m totally biased because I proposed this feature. I couldn’t believe that OpenAPI didn’t already support this common use case and it took time to realise that it wasn’t that I didn’t understand how to do something – that thing really was outside what OpenAPI 3.0 expected APIs to describe.

OpenAPI 3.0 does have support for callbacks so if the user should make an API call, supply a URL, and stand by for incoming HTTP requests to that URL as a result, that’s already supported. This is ideal when an endpoint asynchronously returns data, or for some situations where an API call “subscribes” to an event and gives a URL to send things to.

OpenAPI 3.1 goes a step further and allows webhooks which are incoming HTTP requests that are in response to some external event or stimulus. A great example would be if you’ve ever linked anything to a GitHub push event, or an incoming order/payment/message (and I’ve been working for a communications company for a few years, so you can immediately understand how I got entangled in this). The webhooks are described a LOT like the existing callbacks are, and indeed both are much like the existing request descriptions, so I hope this change will be easily adopted by everyone who has a two-way API like this.

The new webhooks keyword is a top-level element, alongside paths. There are also changes to the required fields: OpenAPI 3.0 required openapi and info and paths but in OpenAPI 3.1 only openapi and info are always required, but the document must also contain at least one of paths or webhooks or components. This is brilliant because it allows API descriptions to contain only outgoing API calls, only incoming webhooks, only components that might be referred to by other documents, or any combination or all of these – and still be valid in its own right.

Anyway, back to the webhooks.

webhooks:
  inbound-sms:
    post:
      operationId: inbound-sms
      requestBody:
        content:
          application/json: ...
      responses: ...

Within the webhooks section, each incoming “thing” has a key (such as inbound-sms in the example above) and then it goes on just … looking like a pathItem, because that is all it is. You don’t need to specify the URL path that the webhook will come in on (often the user can nominate that anyway), just explain what will arrive and you are done. Oh and related to this: pathItem is now allowed in the components section and you can $ref to a pathItem from either a path or a callback or a webhook.

Fancy a sneak preview of what the webhooks will look like when the tools get support for it? Redoc already has preview support if you use x-webhooks in your 3.0 OpenAPI documents! I mean, it just looks like really competent API documentation but that’s what we need here 🙂


A note about webhooks and callbacks. Quite a few endpoints could be considered as either a webhook or a callback, and I have already started getting questions about which to use. It probably doesn’t matter but if there is no preceeding API call that the callback is a response to, then it’s definitely a webhook. Where there is some previous API call with a URL, then it’s probably up to you how you want it to work. For example at Vonage the configuration for where to send events for an incoming Message is at the application level, do you do that with the Application API – but I’d rather have the API description with the incoming Message webhook detail shown next to the send Message API call, in the same document, tagged and grouped together in the Message API description. The webhooks keyword gives you the flexbility to approach this as you will.

Small But Perfectly-Formed Upgrades

There are so many small things that have been added in OpenAPI 3.1 but I’m picking my favourites to include! As with every *.1 release, there are things that seemed like a good idea for the *.0 release that can now be tidied up a little now we’ve all tried them out in anger, it’s a good thin.

I’ll start with the one I want to implement immediately (or as soon as the tools allow): $ref can now have summary and description as siblings, and they override any existing fields on the referred-to component.

paths:
  /items:
    post:
      parameters:
        - $ref: '#/components/parameters/item'
          description: The specific item in question

There are a few minor things in the info section as well:

  • Inside info, you can now have summary alongside the description field. Both are optional – title is still required.
  • In the license object you can use an SPDX code in the new identifier field instead of a url alongside the required name field if you prefer

Finally, paths are no longer required to have responses field for every endpoint. This is useful when an OpenAPI document is under construction because it means that it will validate even when you’re still only sketching out the endpoints that the API definition will include.

Further Reading

I’ll share links to my talk when the recording is published (the slides are on notist but keep up with the current status of the OpenAPI 3.1 release and read the (much better) changelogs on the project itself for more information https://github.com/OAI/OpenAPI-Specification/releases.

Close Menu