Presentation for the recent developerWorks Open broadcast 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.

1. The Open API Initiative:
6 Months and Counting
July 27, 2016

2. Brief Introductions
• Jeffrey Borek (@jeffborek)
– Open Tech & Partnerships, IBM
• Dennis Brennan (@dennis_brennan)
– Capital One Digital Engineering
• Raymond Feng (@cyberfeng)
– API Architect, StrongLoop – an IBM company
• Marsh Gardiner (@earth2marsh)
– Product Manager, Apigee
• Tony Tam (@fehguy)
– VP of Swagger Products, SmartBear Software

3. Agenda
• Panel (35 minutes)
– Introduction
– API Challenges/Attraction/Background
– What is what?/Details/How’s it going?
– The OAI/Current Membership/Governance
– OAI Spec/Feedback & Categories/Change Criteria
• Round Table Discussion (15 minutes)
• Q&A (10 minutes)

4. Creating APIs remains challenging…
As a consumer
What do you call? Read the docs?
Hope for a (decent SDK)?
What are the parameters?
What is the payload?
As a provider
Accurate documentation is hard
Making SDKs is hard
Supporting users is really hard
And in general…
Writing boilerplate code blows

5. What attracted developers/companies to the Swagger
Project?
• A common, public contract between
services
• Independent of language, framework,
deployment technology
YAML or JSON format
• Supports both API-first and code-first
approaches to defining, building and
documenting APIs
• Broad industry/developer adoption

6. Swagger Project background
• Swagger Project founded in 2010 by
Tony Tam / Reverb to design and
document API interfaces
• Groups large & small drawn to Project
Interested in its simplicity, pragmatic
approach, potential open governance
• Acquired by SmartBear in early 2015
• Decision to form a Linux Foundation
Working Group Project in late 2015
• Swagger Spec donated by SmartBear
Software to the Open API Initiative

7. What is what?
Swagger?
OAI?
OAS?
Open API?

8. • The Swagger Specification is now called the OpenAPI Specification
– The existing Swagger Specification is the OpenAPI Specification
– There are no changes in the existing specification
• The next version will be “de-Swaggered”
• The next version will be OAS 3.0
Details, details, details
Until OAS
3.0, Swagger
Spec = OAS

9. How is (ehm…) OAS 2.0 doing? ;-)
27 July 2016
• ~18k/daily downloads**
• Over 3k known public GitHub
repos
• 44 targets in codegen from > 350
contributors
• Natively supported by all major
APIM solutions
– AWS
– IBM
– Microsoft

10. The Open API Initiative (OAI)
• Provide an open source, technical community, within which industry
participants may easily contribute to building a vendor-neutral, portable
and open specification for providing technical metadata for REST APIs
• The OAI is a collaborative project under the guidance of the The Linux Foundation.
LF Projects use open source governance best practices, including license and
contribution agreement choices, in keeping with the ideals of Linux

11. OAI Membership (17 organizations as of July 2016)

12. OAI Governance Structure
• Business Governance Board (BGB)
– The BGB shall be composed of one representative appointed by each OAI Member; responsible
for trademarks, certification, budget
• Technical Oversight Board (TOB)
– Responsible for managing conflicts, violations of procedures or guidelines and any cross-project
or high-level issues that cannot be resolved in TDC
• Technical Development Community (TDC)  Open to all
– Manages the Open API Specification development

13. OAI Spec Current and Future Status
• https://github.com/OAI/OpenAPI
-Specification (current 2.0)
• When properly defined via
OpenAPI, a consumer can
understand and interact with the
remote service with a minimal
amount of implementation logic
• https://github.com/OAI/OpenAPI-
Specification/tree/OpenAPI.next
(working branch 3.0)
• All development activity on the
future specification will be
performed as features and
merged into this branch. Upon
release of the OpenAPI
Specification, this branch will be
merged to master

14. Gathering Feedback / Categories of OAS Meta Issues
• Thousands of reports on
GitHub / Google Groups /
IRC
• OSS tooling requests /
Implementation challenges
• Following the evolution of
API design and looking
ahead
1. Document Structure
2. Payloads + Schemas
3. Security
4. Paths
5. Parameters
6. Specification document
structure
LInk to Meta Issues in OAI GitHub Repo here:

15. OAS 3.0 Specification Change Criteria
• Clarity - The current "way" something is done doesn't make sense, is complicated, or
not clear
• Consistency - A portion of the specification is not consistent with the rest, or the
industry standard terminology
• Necessary functionality - We are missing functionality because of a certain design of
the specification
• Forward-looking designs - As usage of APIs evolves to new protocols, formats,
patterns, we should always be considering what the next important functionality should
be
• Impact - A change will provide impact on a large number of use cases. We should not
be forced to accommodate every use case. We should strive to make the common and
important use cases both well supported and common in the definition of the OAI
Spec. We cannot be edge-case driven

16. Round Table Discussion
https://openapis.org/

17. Get involved with the OAI community
Join the technical community and engage with projects!
– Get involved in creating the next version of the OpenAPI Spec
• https://openapis.org/news/blogs/2016/07/you-can-get-involved-creating-openapi-
specification-and-heres-how
– IRC: #openapis at irc.freenode.net
– Twitter: @OpenApiSpec
– GitHub
• https://github.com/OAI/OpenAPI-Specification URL
• https://github.com/OAI/OpenAPI-Specification/tree/OpenAPI.next
• https://github.com/swagger-api
What role would you/your company like to play in the OAI?
– https://openapis.org/join

18. Open Q&A
https://openapis.org/