Getting Started with API Standardization in SwaggerHub
Download as PPTX, PDF0 likes587 views
This document provides an overview of a presentation on standardizing API documentation using SwaggerHub. The agenda includes an introduction to SmartBear and their tools, why standardization is critical for API quality, defining quality for teams, challenges of OpenAPI Specification development at scale, and how SwaggerHub can help address those challenges. It discusses how SwaggerHub provides a central hub for designing, documenting, and collaborating on APIs to improve efficiency, quality and reduce defects.
Getting Started with API Standardization in SwaggerHub
- 1. Getting Started with API Standardization in SwaggerHub
- 2. Proprietary & Confidential Jonathan Fortunati Solutions Engineering Manager SmartBear Patrick Londa Marketing Manager SmartBear Your Hosts for Today
- 3. Agenda 1. Introduction 2. Why Standardization is Critical 3. Defining Quality for Your Team 4. Challenges of OAS Development at Scale 5. How SwaggerHub Can Help 6. Time for Q&A Proprietary & Confidential
- 4. Introduction
- 5. We provide tools for development, testing, and operations teams to create great software, faster than ever. • HQ in Boston, MA, USA, with 7 offices globally • Founded in 2009 • Open Source Innovator (Swagger & SoapUI) 6.5M+ Users 194 Countries 22K+ Companies TestComplete SoapUI Pro SwaggerHub CrossBrowserTesting QAComplete AlertSite
- 6. Design Commit Test Deploy Monitor Manage UI API Collaborate on user stories, tests, and code Commit and push new code and tests to kick off CI Create, manage, and execute automated tests Deploy to production once tests and builds pass Monitor the performance of your APIs and web apps Analyze and improve all of your testing Reduce defects and improve trust with code review SwaggerHub Design, model, & share API definitions CucumberStudio Design features & tests using BDD Zephyr Native Jira & enterprise test management Review Collaborator Code, document, & artifact review CrossBrowserTesting Run Selenium & Appium tests in the cloud LoadNinja Automated UI performance testing TestComplete Automated UI functional testing ServiceV Pro Virtualize APIs, UIs, and web services LoadUI Pro Automated API performance testing SoapUI Pro Automated API functional & security testing AlertSite Global, synthetic API monitoring Accelerate & manage API functional testing Test mobile apps on real devices in the cloud BitBar
- 7. Why Standardization is Critical
- 8. The 2019 State of API Report
- 9. Quality is King API consumers expect efficient, high performance services that are easy to use. API developers recognize quality as a top priority. 41.5% say it is ‘Extremely Important’ 78.5% say it is ‘Very Important’ or higher Poor API quality has real consequences. 45% relate poor quality to potential loss of customers 48% worry about damaging company reputation
- 10. Standards Enforce Quality Standardization is the #1 challenge teams are looking to overcome in the new year. Versioning and re-use also important considerations, with speed being a key driver. Over 50% of organizations use, or plan on using an internal style guideline. Style guidelines were ‘important’ or higher for over 50% of respondents.
- 11. Defining Quality for Your Team Reusable Components Shifting Left Driven by the OAS Document & Consumer The OpenAPI specification is the industry standard for designing and building quality RESTful APIs and SmartBear is a leading sponsor of the project Enable shift-left transformation through definition-driven development, virtualizing and testing definitions before code is written. Improve efficiency by sharing API definitions, virtual services, and code snippets throughout your development lifecycle for maximum reuse. We believe documentation is at the core of a consumable, shareable API that fosters a positive experience in the developer community.
- 12. 12 Phase 1 Individual Devs Write or Generate OpenAPI Definitions Phase 2 More People Get Involved and All New APIs Have OAS Phase 3 New Processes and Tooling Need to Be Implemented 3 Phases of OAS Development
- 13. 13 OAS Development Challenges 1. Too many versions of too many specs in too many places 2. Too many people involved that need to collaborate and share 3. Loss of control and visibility into API design process 4. Integrating API development into existing delivery pipeline
- 14. Swaggerhub A platform that ties together all the open source Swagger tools in one place. • SwaggerUI • Swagger Editor • Swagger Codegen Creates a single source of truth for distributed services. Provides structure and guidance across teams: • Team / Organization Management • API Standardization Checks • Domains { }…
- 15. 15 Challenge 1: Too many versions of too many specs in too many places A central ‘hub’ for designing + documenting APIs: Allow teams to work together on a core piece of their development Resolve issues sooner with more input from consumers, users and other teams Initiate a significant return on investment Plan Design Develop Test Monitor $0 $0 $100 $250 $1500 COST OF RESOLVING DEFECTS
- 16. 16 Challenge 2: Too many people involved that need to collaborate and share Work in teams and foster cross-functional feedback: Bring in the right stakeholders early to create consensus and reduce rework Organize users into different teams and projects Assign access and permissions as needed { }…
- 17. 17 Challenge 3: Loss of control and visibility into API design process Set standards and ensure compliance while designing: Define API standards in one place and enforce across your organization without manual validation Supplement your style guide with custom rules that might be unique to your industry Create a library of reusable assets to ensure consistency and reduce design duplication
- 18. 18 Challenge 4: Integrating API development into existing delivery pipeline Connect across your API lifecycle with integrations: Keep source code in sync with API designs Push APIs to API gateways like Azure, AWS, and Apigee for consumption Leverage your API contract in your CI/CD pipeline
- 19. Thank You!
Editor's Notes
- #7: Alternate view of the portfolio vs. Slide 12 “SmartBear Product Portfolio = Breadth and Depth”
- #13: When we talk about “developing APIs with OAS at scale”, what do we really mean? What we really are talking about is the evolution teams go through as they go from trying the OpenAPI Specification on a few APIs to standardizing on the OpenAPI Specification across all of their internal and public facing APIs. We really think of this in three phases: -Phase 1 typically starts with individual developers either writing API specs or using annotations to generate an OpenAPI definition. In this phase, teams may be using OAS for documentation but there usually isn’t much standard process for how APIs will be documented. -Phase 2 is typically where we see at least 1-2 teams really starting to embrace OAS as a critical step in their API development. This is generally where teams begin to transition to more a “design first” approach for at least a subset of their APIs. -Phase 3 is the point where organizations decide to standardize on OAS. There are multiple people or teams involved in the design process and this is where the need to evolve your toolset will begin. SLIDE
- #14: We’ve laid out what’s involved with scaling your API development with OAS, but as you may know there are also challenges that can get in the way of reaching success. Challenge 1: Too many versions of too many specs in too many places -No standard place for people to find the most up-to-date version of the API Challenge 2: Too many people/teams involved that need to collaborate and share -Collaboration between different teams can be difficult when facilitating the lifecycle of an API from design to deployment -Feedback is key but without one place to track feedback, there is no way to track the work that’s being done Challenge 3: Loss of control and visibility into API design process -Enforcing standards across APIs can be nearly impossible -Lack of consistency in how APIs are designed/documented will lead to issues in the implementation and a poor developer experience Challenge 4: Integrating API development into existing delivery pipeline -Open source tools are great when working on a small set of APIs, but when you are working across tens/hundreds/thousands APIs, you need the tooling you work with to integrate into your existing workflows seamlessly
- #16: Overview of how SwaggerHub helps address challenge 1 – focus on value prop of having one central source of truth for all your work with OAS
- #17: Overview of how SwaggerHub helps address challenge 2 – focus on value prop of communication and the ability to manager and control access to users
- #18: Overview of how SwaggerHub helps address challenge 3 – focus on value prop of API standardization and domains
- #19: Overview of how SwaggerHub helps address challenge 4 – focus on value prop of being able to tie into your different tooling through integrations and the SwaggerHub API