All Posts By

Jeff ErnstFriedman

Join us for the OpenAPI Spec Workshop

By Blog

The Open API Initiative and Capital One are co-hosting a OpenAPI Spec Crash Course as part of the 2016 APISTRAT Conference.

Register here.

Part I: Introduction to the Open API Specification

This workshop will provide an introduction to the new Open API Format for specifying APIs. The format is the core specification of the Linux Foundation’s Open API Initiative and is the most widely used API definition formation. The workshop will include:

  • An overview of the Open API Format and it’s origins in the Swagger specification.
  • Details of when, where and how to use the OAI format with speakers covering live examples.
  • A high level overview of where the format is headed.


Part II: Deep Dive into the Open API Specification

The second portion of this workshop provides a deep dive into the Open API format for users and those evaluating the format. The format is the core specification of the Linux Foundation’s Open API Initiative and is the most widely used API definition formation. Topics covered in this portion of the workshop include:

  • A technical deep dive into the Open API Specification including worked examples.
  • An overview of tools and services which use the format.
  • A session on the upcoming v3 format and what it is likely to contain.
  • Information on how to get involved in the OAI and contribute to the Open API Specification.


Request Parameters: Explaining the 3.0 spec, part 3

By Blog

With the version 3.0 of the OpenAPI Specification nearing a beta candidate, this series of posts is meant to provide insight into what is changing and how from the perspective the Technical Developer Community (TDC). The first post described the background and rationale behind the next evolution of the spec, the second covered Structural Changes, and the next few posts will address Protocol, Documentation, and other remaining open items.

Request Parameters

In OpenAPI 2.0, all the pieces of the request message that can vary, including URL parameters, headers, and body, were described as a set of typed parameters. Experience has shown that mapping the description of a HTTP request body into the same set of metadata as query and header parameters presents a number of challenges. Today, let’s break down how this will affect the request body, content objects, and cookie parameters.

Request Body

A new property requestBody has been added to the operation object. As a named property, this provides better distinction from and simplifies the parameter object, plus it makes it easier to describe the request body itself.

Content Objects

OpenAPI 2.0 established a complex relationship between:

  1. Where response media types are declared
  2. Where response schemas and examples are defined

Multiple response media types could be defined globally but optionally overridden at the operation level. However, that provided for one schema to be defined per response object, though examples could be defined by media type, and/or one per schema. This made it difficult to define different schemas for different media types and to use different media types for different response objects.

To address this, the content object introduces a simple relationship between response objects, media types, and schemas. Each response object contains a single content type object for each supported media type. Each content type object has a single schema and an array of examples for that media type.

The content object is also used for the request body and works identically for describing the inbound payload. This has the magic result of removing the need for the produces and consumes arrays. Discussions are ongoing about whether to also leverage content objects to describe complex URL parameters and response header values.

These changes result in a path item with this structure:


Cookie Parameter

While TDC members unanimously agreed that while using cookies is not a best practice for passing parameters, enough people had expressed the desire to describe existing cookied-based APIs that it warranted the inclusion of a new parameter type.

In the next post we will cover new interaction patterns to be supported and some planned changes for payload descriptions.