Skip to main content
search
Category

Blog

Nov 01
Love0

OpenAPI Spec at APISTRAT 2016

By Blog

The Open API Initiative (OAI) is focused on creating, evolving and promoting a vendor neutral API Description Format based on the Swagger Specification. As an open source project under the Linux Foundation, the OAI is committed to developing and promoting the OpenAPI Spec for use by all. We welcome contributions from members and non-members alike.

There are many things you and your organization can do to help to community.

  1. Leverage the spec: There are no fees or membership requirements to use the OpenAPI Specification: GitHub | OpenAPI Specification
  2. Develop the spec: All members of the community are invited to take part in conversations on how to evolve the spec. Find one of our meta issues that applies to your project. If you don’t see one here log a new issue.
  3. Share how you use the spec.
  4. If you are looking to support the project directly, consider having your company join the OAI as a member. Fill out this form to learn more. The project charter is here.

Not sure how to get started? Read how to participate here.

Learn More at APISTRAT 2016

November 3rd

API DESIGN & GOVERNANCE | 11:00 am – 12:30 pm
Matthew Reinbold, Lead, API Center of Excellence, Capital One DevExchange
What happens when a company decides to API everything? Organizations may be quick to follow Netflix and Amazon in the pursuit of microservice and service orientated architecture (SOA). But without the application of Conway’s Law, any governance effort (and, by extension, the API program) will fall short. Matthew has been instrumental in establishing and growing API governance programs at multiple enterprise companies. In this talk he will discuss effective API governance and the challenges in achieving it.

MICROSERVICES: gRPC or REST? Why not both? | 11:00 am – 12:30 pm
Sandeep Dinesh, Developer Advocate, Google Cloud
In this talk, Google’s Sandeep Dinesh will show you how you can build a gRPC endpoint that can intelligently serve gRPC over HTTP/2 while simultaneously serving JSON/REST over HTTP/1.1 on the same port! Then, he’ll walk through some benchmarks and best practices for deploying these microservices in a scalable way. Read more here

HYPERMEDIA:

Hypermedia vs Graphs: Best buddies or the next API battleground? | 1:30 pm – 3:00 pm
Gareth Jones, Microsoft
We all wonder if this is the year that hypermedia becomes mainstream? But coming up on the rails, there is a new challenger: Graph-shaped APIs that predefine a wide network of relationships promise some of the benefits of hypermedia APIs, but present a more familiar programming model. Will graphs push aside hypermedia before it’s even had a chance, or will both styles play nicely? Is this trend a blocker to HATEOS nirvana or a stepping stone?
I’ll challenge the audience to consider combining these two approaches to open the door to mainstream hypermedia use, enriching a fixed graph with dynamic data and behavior. Volatile data and logic can use hypermedia and more foundational data can use graph approaches. In this way we can add value and depth to our apps without the drastic rewrites we so often expect from the transition to hypermedia. Read more here

 

ENTERPRISE:
Breathing new life into legacy SOAP services | 3:05 pm – 4:35 pm

Darrel Miller, Software Developer, Microsoft
The reality is that SOAP services are no longer cool. Developers today want to integrate with APIs that are labelled REST. They want descriptive URLs, JSON payloads and familiar HTTP status codes. But many enterprises spent 10 years building SOAP services and many of those services are working just fine today. Rewriting them would be a huge effort with the risk of minimal gain. The good news is that it is possible to give developers what they are looking for without a re-write. You can take advantage of HTTP’s layered architecture to put a façade in front of your SOAP services, re-use all your existing code, breathe new life into your service and still support the existing client applications that are happily sending SOAP messages.This talk will explore the process of transforming native HTTP requests into SOAP messages and back into native HTTP responses. We will discuss which parts of the façading process can be automated and which parts require design decisions. Finally we will explore what capabilities we gain with this new style of API, and what we lose, so that you can make an informed decision on the future of your SOAP services.

The Big Problem with the Big Picture | 3:05 pm – 4:35 pm
Amber Fallon, SmartBear Software
APIs are BIG. Bigger than many of us, even those of us in the industry, may realize – in fact, the total number of public APIs has exploded from under 7,500 in 2012 to over 15,000 in 2015. Larger companies have larger API structures, with more dependencies and integrations than ever before, and that number is growing. Entire business models have formed around the APIs provided by some of the industry’s heaviest hitters. Imagine app juggernauts like Uber or Waze functioning without Google Mapping technology, or the important relationship between Netflix and the underlying applications that power its video streaming – these applications are absolutely dependent on their underlying APIs. And, new applications dependent on public APIs crop up every single day.
With that scale come challenges like managing your public API in a way that will foster growth of dependent APIs, scaling up, maintaining your SLA, and allowing for the versatility of user created applications; your API may be used in ways you never envisioned. In this session, I’ll address challenges like sandboxing at scale, aiding in end user integrations, and managing the infinite number of dependencies larger APIs may encounter.

How Low Can You Go? Reducing Costs and Development Time with AWS Lambda, API Gateway, Elastic Beanstalk, and 3scale (and don’t forget Swagger!) | 9:05 am – 9:30 am
Erin McKean, Founder, Wordnik
More than 18,000 developers have keys to the Wordnik API, which they use to build everything from edtech applications to word games to Twitterbots! Our original architecture has served more than 2bn calls since 2010, and has largely been a free service. When Wordnik relaunched as a nonprofit in late 2014, we realized we had to monetize our API to create a sustainable foundation for future development, and in order to monetize, we needed to reduce our operating costs and introduce new features — neither of which our previous architecture made simple. Enter AWS Lambda+API Gateway! By breaking down our current API into tiny functions, we can take advantage of the current microservice craze with minimal ops headaches. And by using Elastic Beanstalk and 3Scale to manage a reverse proxy, handling routing between the old and new API calls and managing billing is much easier, too. Add a pretty Swagger interface on top and you”re good to go … faster and cheaper!

November 4th

TESTING AND MONITORING:
Testing your APIs with Cucumber | 11:15 am – 12:45 pm
Ole Lensmar CTO, SmartBear Software
BDD with Cucumber is gaining in popularity as it allows the expression of requirements using a custom domain-specific language that can be executed as tests to validate actual implementations. APIs in particular seem to have a lot to gain from this approach as they are often technical in nature; it seems that a correctly performed Cucumber implementation should allow increasingly non-technical stakeholders to participate in defining the requirements for an APIs behaviour and functionality. But how “non-technical” can cucumber vocabularies be made to describe something as inherently technical as APIs? When does it make sense to use imperative vs declarative approaches? How do you translate simple language to complex payloads and validations? How does the usage of Cucumber scale as the complexity of an API increases? And how can standards like Swagger make cucumber testing even more intuitive? I know you’re dying to find out – so don’t miss this opportunity to adopt the path of API Gherkin Nirvana!

FINTECH:
OpenAPI Trek Beyond API Documentation | 2:00 pm – 3:30 pm
Arnaud Lauret IT Architect, AXA Banque
OpenAPI offers many possibilities that span the full API lifecycle, yet it is seen purely as a solution for generating API documentation. This session will tell the story of AXA Banque’s evolution from .doc and .pdf API documentation to the extensive use of OpenAPI Specification (formerly Swagger). Throughout the journey, we will identify the many advantages of API definition languages beyond simply generating API documentation, including design, testing, documentation continuous delivery, code generation, mocking, and prototyping new ideas.

RESTing on the Shoulders of a Giant: How Capital One Builds Its APIs | 2:00 pm – 3:30 pm
Abdelmonaim Remani, Engineering Tech Lead, Capital One DevExchange
Since it was first introduced, the REST architectural style was plagued with a high degree of vagueness and a lot of ambiguity. The absence of a concrete reference implementation early on left it up to the most popular web APIs to establish themselves as the gold standard. To win the hearts and minds of every last web developer, the leading tech companies invested greatly in building RESTful APIs, and put tremendous resources behind evangelizing their own individual flavors of REST. Capital One is no exception to the rule. As counter-intuitive as it may seem to be for a financial institution of its caliber, and as challenging as it is being a player in an industry locked into archaic technology and restrained by regulations, Capital One is fully engaged in a company wide initiative to expose financial services through internal and public-facing APIs implemented in the latest and greatest open source technologies. This talk is about how Capital One does REST, where the stakes are much higher and the risks are well beyond giving customers the wrong turn-by-turn directions.

Full Lifecycle Tool Support for APIs | 2:00 pm – 3:30 pm
Steven Fonseca, Principal Services Architect, Intuit
The focus of the talk is showcase an internal Intuit tool called API Lifecycle Manager, a web app and set of APIs that enables the IT organization to produce APIs efficiently across their lifecycle from conception to retirement. The audience will be provided a glimpse into how Intuit IT coordinates the build out of a strategic portfolio of APIs including their functional allocation and service ownership, comprehensive contract documentation with innovations not found in current industry modeling languages, documentation generation and delivery. Examples of API Lifecycle Manager will be shown in the context of a story of how IT is enabling Intuit product to deliver delightful customer experience, particularly in the areas of subscription-based billing and commerce.

THANK YOU

The Open API Initiative is proud to sponsor this year’s APISTRAT 2016 in Boston Nov. 2-4. Join OAI members: 3Scale, Apiary, Capital One, Cloud Elements, IBM, Intuit, Microsoft and SmartBear as we discuss the API economy. The seventh edition of the conference will bring together everyone – from the API curious to today’s leaders – to discuss opportunities and challenges in the API space.

 

Oct 25
Love0

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.

 

Oct 14
Love0

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:

contentobjects

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.

Oct 03
Love0

TDC: Structural Improvements: explaining the 3.0 spec, part 2

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. The first post described the background and rationale behind the next evolution of the spec, and the next few posts will address the progress made by the Technical Developer Community (TDC) so far.

In an effort to organize the work, six omnibus meta-issues have been created:

  1. Structural improvements
  2. Request Parameters
  3. Protocol and Payload
  4. Documentation
  5. Security
  6. Path definitions

Over the next couple of weeks, we will describe each in order. Today, we’ll cover…

Structural Improvements

The next version of OpenAPI will have some pretty significant changes—in semantic versioning terminology, this will represent a major change from 2.0 to 3.0. Since breaking change events happen rarely, they present the opportunity to make sweeping structural improvements.

Most importantly, with the OpenAPI Specification version 3.0, the overall structure of the document has been simplified:

pasted-image-0

New Version Identifier

One obvious place to begin the transition from the description that was once called Swagger 2.0 and is now known as the OpenAPI Specification? The version property that was called swagger from 2.0 will be replaced by an openapi version identifier. Going forward this version identifier will follow the conventions of semantic versioning, and therefore it will have three parts: major.minor.patch, which likely means 3.0.0. This also explains why the value is a string rather than a number, and it will allow for more controlled and identifiable changes to the specification in the future.

Components Objects

OpenAPI 2.0 was somewhat inconsistent in the behavior of root-level properties. For example, some properties contained metadata that was applied globally to the API, while other properties were used as containers for reusable fragments of metadata to be referenced elsewhere. In order to clarify this and to minimize the number of properties at the root level, a new components property will be introduced. This components property contains only reusuable metadata that will be referenced elsewhere in the document.

pasted-image-0-1

Multiple Hosts

OpenAPI 2.0 allowed specifying a single host and basePath, and yet the schemes attribute allows specifying both http and https, therefore effectively enabling two hosts that only vary in the scheme. In the OpenAPI.vNext, the working branch of the spec repo, a new root level hosts object contains an array of objects that contain host, basePath, and scheme properties. By structuring this as an array of objects, any number of root URLs for the API can be supported, and it allows for a clearer correlation of the scheme, host, and basePath properties. It also reduces the number of root level properties required, simplifying the document structure.

hosts

During the discussions around the GitHub issues and associated pull request, the TDC addressed the question of whether paths might be identified as representing different environments, such as dev, test, and production. However, this would have suggested that different hosts might point to different API implementations, and that was not the intent behind supporting multiple root URLs for the API. Rather, the goal was to allow a set of aliases to be defined for the same API. (Note: there remains an open issue concerning parameterization of the host and basePath, which might allow for pointing to different environments.)

Additionally, the host, basePath, and scheme may be overriden at the path item level. This should make it easier to incorporate functionality provided on a separate host into an API description.

pasted-image-0-2

More Descriptive Options

The new specification allows users to describe their APIs in a more resource-oriented manner. Previously, descriptions of API behavior were defined at the operation level. For APIs designed in a resource-oriented way, documentation text would often read “GET a foo”, “POST a foo”, “DELETE a foo”. If the purpose of “foo” needed to be elaborated upon, it became necessary to somewhat duplicate that text for each operation. Now a Path Item Object can contain both a short summary text and a longer description text. The choice to provide additional description at the operation level is left up to the user, based on whether further explanation is required.

Examples Object

The options for describing examples have been significantly expanded. The previous specification indicated that examples could only be described by a JSON or YAML object. Now, by using a JSON string, any format of example can be described. Additionally, a $ref object can be used to point to external files containing examples. The exact method of structuring examples is still in flux and may depend on whether the proposed content object is accepted by the TDC. The content object contains an array of example objects for defining a one or more examples for each media type.

As you can see, this one meta-issue about the structural changes has a lot to digest. The next post will discuss changes to how requests are described in OpenAPI 3.0.

  • Previous post in this series Part 1 – Background and how to get involved!

 

—
Darrell MillerAbout The Author
Darrel Miller
Darrel Miller is a Senior Software Development Engineer on Azure API Management for Microsoft. Darrel is a member of the OpenAPI Specification Technical Developer Community. You can follow him on Twitter or on his blog Bizcoder.

Sep 26
Love0

Open API Initiative, 9 Months and Counting – OAI Meetup 2016-09-15

By Blog

At the OAI Meetup on Sept 15, Jeff Borek of IBM took the audience on the journey the Open API Iniative has taken over the last 9 months. Starting with a brief overview of the Open API Initiative, some background on the Swagger Project that it’s based upon, and ending on how many companies today are collaborating to enable open governance of the OAS 3.0 Spec – as it approaches completion later this year.

—

Jeff BorekAbout The Author
Jeff Borek
Jeff Borek (WW Program Director for Open Technology & Partnerships, IBM) is a senior technology and communications executive with over twenty years of leadership and technical experience in the Software, Telecommunications, and Information Technology/Consulting industries. He is currently the business development lead for the Open Technologies and Partnerships team – working with clients, business partners, leading industry analysts, and various open source community initiatives including; the Linux Foundation, the OpenStack cloud software project, and the Cloud Foundry Foundation. He also represents IBM as the current Chair on the Docker Governance Advisory Board, but most importantly for us he serves on the board of the Open API Initiative. You can follow him on Twitter.

Sep 19
Love0

OpenAPI Spec at Google – OAI Meetup 2016-09-15

By Blog

Before the precursor to the OpenAPI Spec – the Swagger Specification – was created in 2010, Google had already published 150 public APIs, leveraged by hundreds of thousands of developers and handled many, many billions of calls … every day.

At the Sept. 2016 OAI Meetup, Dan Ciruli discusses why in a product post mortem the API team was lead to an open source solutions and eventually join the Open API Initiative.

After getting the details on why they joined, hear what they are doing with it. On Sept. 1, Google announced the open beta release of the newest set of features and open source components in Google Cloud Endpoints. Find out why Google is committed to leveraging the OpenAPI Specification and what they are cooking up next.

Slides from Dan’s presentating can be found here:

—
Dan CiruliAbout The Author
Dan Ciruli
Dan Ciruli is a product manager at Google who works on API infrastructure. He used to play a lot of ultimate when he had knees and write a lot of software when he had time. He’ll try to speak Spanish to you if you give him a chance. You can find him on Twitter at @danciruli.

Sep 19
Love0

Zipping through the OpenAPI with Capital One – OAI Meetup 2016-09-15

By Blog

Statically defined processing in your API stack is so last year. Learn about the the new and interesting ways Capital One is using the OpenAPI Specification to enable more flexible and open API development.

Follow along with Capital One developer Leonhardt de Waal as he zips through the OpenAPI Specification.

Note: Due to technical difficulties, we, more so the project’s PM, but we’ll forgive him this one time, the presentation cut out and is in two parts. We apologize for the inconvenience.

Part 1

Part 2

 

—
About The Author
Leonhardt de Waal
Leonhardt is a software engineer at Capital One.

Aug 01
Love0

Open API Initiative: Six months and counting (Recording)

By Blog

Watch a recording of IBM developerWorks Open where OAI Board member Jeff Borek (@jeffborek) moderates a discussion with fellow OAI members Capital One’s Dennis Brennan (@dennis_brennan), Apigee’s Marsh Gardiner (@earth2marsh) and Tony Tam (@fehguy) of SmartBear Software along with Raymond Feng (@cyberfeng) of StrongLoop.

Six months and counting

 

Links

Jul 11
Love0

You Can Get Involved in Creating the OpenAPI Specification, And Here’s How

By Blog

How is the OpenAPI Specification evolving? What’s the process? How can you get involved? Today we’ll try to answer those questions and shine a light on:

  • The Technical Developer Community, why it exists and how it operates
  • The timeline and roadmap for the next major revision of the OpenAPI Specification

Open API Logo

Last December, the Swagger 2.0 specification was donated by SmartBear and became the OpenAPI Specification (sometimes abbreviated OAS). The spec is 100% compatible, only sporting a new name and brand. Why was this important? In some ways it doesn’t—there was nothing “broken” before. However, in order for sometimes-competitive vendors to build support for the format into their products and to collaborate on an industry standard, they needed a neutral governance model. This is exactly why the Open API Initiative was created under the Linux Foundation in order to evolve what was once known as the Swagger specification.

_meta_issue_specification_documentation_structure_and_supporting_docs_issue_589_oai_openapi-specificationThe Open API Initiative’s charter created, “an open source, Technical Developer Community (TDC), open to any participant, whether an OAI Member or not. ” The TDC is responsible for overseeing the evolution of the OpenAPI Specification. Today, the TDC has six members, and it will grow over time as individual members of the community step up to drive the format. The good news is that ever since the 2.0 specification was launched, people in the community have been offering suggestions for how to improve it. Many of those issues have been identified as candidates for the next major release—the challenge now is to decide what is in or out for the next version and to bring those changes to release candidate status.

In order to tackle the huge backlog of issues, Tony Tam, who founded Swagger and leads the TDC, identified a number of high level themes such as Security and Protocols and Payloads, added references to the individual issues and then tagged them as Meta issues for OpenAPI.Next on GitHub. The single best way to understand the direction that the OpenAPI Specification 3.0 may take is to review those meta issues. Over the next few weeks, Jason Harmon, Darrel Miller, and Marsh Gardinerwill try to break down some of those issues with individual blog posts in order to explain some of the thinking behind them.

clarification_about_yaml_by_fehguy_pull_request_635_oai_openapi-specificationWhile the TDC strives to communicate through issues and pull requests, we’re all volunteers that steal time to work on OpenAPI. Sometimes it’s faster to have an hour long conference call, which we do every couple of weeks. In addition, we use the OAI’s Slack team to raise attention to questions or suggestions when GitHub notifications don’t get the job done. The changes proposed by a sub-issue in a meta issue result in a pull-request (PR), and that PR is then voted on by using a reaction on the issue.

How can you get involved? If you have a particular interest in a topic, search the existing issues and join the conversation or start one if necessary.

Some of those topics are philosophical, such as Is OpenAPI an Open World or Closed World Contract?Some of them are passionate, such as Support for multiple request/response models based on headers. Other topics go deep into questions about JSON-Schema or the YAML specifications. Over the next few weeks, we’ll post here on the blog about some of the meta-issues and sub-issues and give some insight into the nature of the discussions around them.

 

—
Marsh GardinerAbout The Author
Marsh Gardiner
At least two of the following three statements are true about Marsh: No one loves APIs more. He is a developer trapped in the body of a product guy. He hates writing bios.

In the semi-random walk of Marsh’s career, he has produced videogames for EA and Fox, created interactive learning environments, launched an educational non-profit organization, and fought bravely in the API wars of 2009-2018. At Apigee, he imagines a better future for apps and APIs.

Close Menu