Open API Initiative: Six months and counting
Download as PPTX, PDFâ˘1 likeâ˘491 views
The document outlines the progress and structure of the Open API Initiative (OAI) as of July 2016, highlighting the challenges of API creation and the adoption of the OpenAPI Specification (formerly Swagger). It discusses the governance structure of the OAI, including various boards, and emphasizes the importance of community involvement in the development of API standards. Future plans include transitioning to OpenAPI Specification version 3.0, with ongoing discussions about documentation clarity, consistency, and necessary functionality.
Open API Initiative: Six months and counting
- 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
- 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
- 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