Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

The Swagger Format becomes the Open API Specification: Standardizing descriptions of Web APIs for interoperability

2,111 views

Published on

Presentation at Cloud Expo Europe on the evolution of Swagger and the Open API Initiative (http://openapis.org). Slides based on OAI standard slides by others (credits in the deck). Lighthouse image by Joshua Hibbert vin Unsplash).

Published in: Internet
  • Hi there! Get Your Professional Job-Winning Resume Here - Check our website! http://bit.ly/resumpro
       Reply 
    Are you sure you want to  Yes  No
    Your message goes here

The Swagger Format becomes the Open API Specification: Standardizing descriptions of Web APIs for interoperability

  1. 1. The Swagger Format becomes the Open API Specification: Standardizing descriptions of Web APIs for interoperability Steven Willmott CEO, 3scale Inc. steve@3scale.net : @njyx
  2. 2. Credits 2 ▪ Slides from Marsh Gardiner (Apigee), Dennis Brenan (Capital One), Tony Tam (Smartbear), Ole Lensmar (Smartbear) and myself ▪ http://openapis.org/
  3. 3. Who Am I? ▪ http://www.3scale.net ▪ @3scale ▪ Early Swagger supporter ▪ Now OAI Founding Member 3 ▪ CEO of 3scale ▪ Leading API Infrastructure Provider ▪ 700+ Customers ▪ Billions of API Calls Managed
  4. 4. Introduction & Agenda 4 ▪ OpenAPI Specification (OAS) ▪ Open API Initiative (OAI) ▪ Usage and Tooling Examples
  5. 5. The OpenAPI Specification fka “the Swagger specification” DRAFT - Open API Initiative (OAI) 5
  6. 6. What is the OpenAPI Specification? 6 Generally Categorized REST API Description Language More Generally IDL for REST APIs
  7. 7. What does the OpenAPI Specification Offer? 7 A simple format for writing REST service contracts ▪ Are independent from language, development framework, deployment technology ▪ Can be expressed in YAML or JSON format ▪ Support both API-first and code-first approaches to defining, building and documenting APIs ▪ Have a clean & powerful extension mechanism Language Neutral & Machine Readable Format APIs can be defined in JSON or YAML API-First & Code-First Development Powerful Extension Mechanism Comprehensive Tooling Support (core, UI, codegen, editor)
  8. 8. Road to the OAS 8 2010 Tony Tam @Wordnik founded Swagger Q1 2015 Swagger acquired by SmartBear Q3 2015 Linux Foundation Workgroup Forms Q4 2015 Swagger renamed “OpenAPI Specification” 2010 - 2014 Development, Growth, Adoption, Tooling, Community
  9. 9. Adoption & Growth 9 ▪ 100,000 weekly source visits ▪ 11,500 daily downloads ▪ 10,000 daily visitors to swagger.io ▪ 4,600 forks of official repos ▪ 1,700 public repos on GitHub ▪ Client/server support in all popular languages & frameworks Most Popular API Framework
  10. 10. Community 10 December 2014DRAFT - Open API Initiative 10
  11. 11. Broad Industry Adoption 11
  12. 12. Why adopt the OpenAPI Specification? 12 Commitment to Remain Open Portable Vendor Neutral Strong Independent Sponsorship CommunitySimple & Pragmatic Superior Tooling Best Industry Support
  13. 13. The Importance of API Interface Definitions 13
  14. 14. 14 What about Rest Interfaces?
  15. 15. 15 What Spec? Spec Generates Code Spec as Code Code is Spec REST API Development Evolution
  16. 16. Shared Definitions are Crucial ▪ Stable Interface Definition ▪ Managed process around change ▪ Discovery of capabilities ▪ Automation of processes and procedures ▪ Essential at 100’s APIs ▪ Invaluable at 10’s Thousands and Millions 16Photo: Josh Hibbert / Unsplash.com In your organization: inter-team dependencies Across the public Internet: cross- organization discovery & contracts
  17. 17. Shared Definitions are Crucial ▪ Fixed point of Reference ▪ Automation: ▪ Explorers / Docs ▪ Code Gen ▪ Editors ▪ Search ▪ Testing ▪ Change Management ▪ Management platforms ▪ Design Focus 17
  18. 18. The Open API Initiative 18
  19. 19. The Open API Initiative - Mission 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 OpenAPI Specification. 19
  20. 20. OAI Initial Steps ▪ Establishment of a clear, open governance structure for both business & technical direction ▪Swagger specification donated to the Open API Initiative ▪ Meritocratic approach to technical contributions – not pay-to-play ▪ Charter is here: https://openapis.org/governance 20
  21. 21. OAI Governance Structure 21 Business Governance Board (BGB) Budget, marketing, community, etc… Technical Developer Community (TDC) Manages the OpenAPI Specification Technical Oversight Board (TOB) Resolves conflict in TDC
  22. 22. Swagger ➔ OpenAPI Specification (OAS) ▪ Moved from swagger-api 2.0 to OAI GitHub Repository ▪ https://github.com/oai/OpenAPI-Specification ▪ Core TDC elected and working on next version 3.0 of spec ▪ Apache 2.0 License as before ▪ You can/should join the discussion – please do! 22
  23. 23. Focus of OpenAPI Spec 3.0 Aiming for 2016 summer release ~mid July 23 Documentatio n Structure Protocols and Payloads JSON Schema & JSON References URI Support Error Handling/Docu mentation Security Request Parameters
  24. 24. 24 OAS Usage Examples
  25. 25. 25 Code First with Swagger Annotations
  26. 26. 26 Swagger UI Build docs by processing JSON/YAML API Spec The API Spec can be returned from static source or from the running API
  27. 27. 27 API First with Swagger Editor Wrapped Swagger Editor Lifecycle Tooling Manage API Metadata Governance & Review Dynamic Mock Responses
  28. 28. And Finally… 28
  29. 29. Get Involved! Website: https://openapis.org/ Spec: https://github.com/oai Follow: @OpenApiSpec 29
  30. 30. Additional Information 30
  31. 31. 31 OpenAPI Spec’s X-Extensions Additional data added to API definition to extend the specification Always prefixed by "x-" and can have any valid JSON/YAML format value
  32. 32. 32 OpenAPI Spec’s X-Extensions paths: /demo/bankthings: get: summary: Returns a list of Bank Things operationId: getBankThings x-c1-proxy: audit parameters: - $ref: '#/parameters/ApiKey'
  33. 33. 33 From Legacy Java Framework to Polyglot Microservices using OpenAPI @Annotations & Servlet Filters ➔ X-Extensions

×