Enforcing Your Organization's API Design Standards with SwaggerHub
Download as PPTX, PDF0 likes537 views
The document discusses the importance of API design standards and the role of SwaggerHub in enforcing these standards to enhance API quality and adoption. It highlights the challenges of API standardization, which is crucial for ensuring a consistent consumer experience and maintaining API consumer loyalty. Best practices for API governance are outlined, emphasizing a design-first approach and the gathering of stakeholder input to align APIs with business purposes.
Enforcing Your Organization's API Design Standards with SwaggerHub
- 1. Enforcing Your Organization’s API Design Standards with SwaggerHub
- 2. Calvin Fudge Product Marketing Director API Lifecycle Solutions Alex Bonstrom Solutions Engineer API Lifecycle Solutions Today’s Presenters
- 4. 4 4 APIs are the foundation… Any Application Any Device Anywhere Anytime Instant messaging AR/VR telepresence Document / database sharing Webcasting Telephone Email Enterprise social network Enterprise applications Smart watch Head- mounted displays Laptop/desktop Tablet Smartphone Home Work On the go Qualityisessentialtoensureapplicationswork APIs are essential to ensure connections
- 5. Integration is fundamental to APIs | APIs underpin internal integrations | APIs intersect with a myriad of tools and technologies – SCM repositories, build tools, gateways… | APIs are expected to seamlessly integrate CI/CD Pipeline Deploy Repo
- 6. 6 API Design Matters | Development teams today are distributed across departments, geographies, time zones | Consistency in API design is not a given o Code-first, design-first | Without a focus on API design standards, it is difficult to create a consistent API consumer experience
- 7. API adoption is tied to consistent design | If an API is to be used, consumers need a guide to help them understand o What data is the API providing o What is its functionality o API protocols, formats, versions Gartner: How to Design Great APIs, June 15, 2021 “APIs designed without a disciplined commitment to consumer-centricity will suffer poor adoption and fail to meet user expectations.” SwaggerHub Embedded Style Guide Flagging Standardization Error
- 8. 8 State of API 2020 - Standardization Tops API Challenges | Standardization ranks as the top challenge for all organizations as they attempt to scale API development. The State of API 2020 Report, © 2020 SmartBear Software. All rights reserved. 59% 45% 39% 37% 37% 38% 36% 26% 1% 25% 10% 40% 38% 23% 18% 22% 12% 1% 0% 20% 40% 60% Standardization Versioning Security Easier Integration Between Tools Composability/Multi-Purpose Re-use Authentication Scalability Discoverability Other (please specify): Which API technology challenges do you most hope to see solved in the near future? (Select all that apply) 2020 All Responses 2016 All Responses | Doubling in importance since 2016!
- 9. 9 Standardization impacts API Consumer Loyalty | API Consumers are less loyal now than in previous years. | When faced with quality or performance issues | First report | Second – leave! | Willingness to leave went from 30% in 2016, to 37% in 2020. 0% 10% 20% 30% 40% 50% 60% 70% 80% 90% Wait for the problem to resolve itself Report the problem publicly (i.e. online forum/community, social media) Report the problem to other external people that could be affected (Peers, customers, partners etc) Review service level agreements Switch to an alternate API provider temporarily Consider switching API providers permanently Report the problem internally to others within your organization Report the problem to the API provider As an API Consumer, how do you react upon encountering quality or performance issues with 3rd party APIs? (Please select all that apply) 2020 2018 2016 The State of API 2020 Report, © 2020 SmartBear Software. All rights reserved.
- 10. 10 Best Practices: API Standardization and Governance 1. Gather input from all stakeholders to ensure API design aligns to business purpose 2. Understand your API workflow 3. Design-first is preferred over code-first 4. Leverage a single source of truth for API definitions 5. Utilize an API style guide as initial step toward governance 6. Leverage custom rules to validate OpenAPI definitions for compliance with API design guidelines Asset Library API_1 API_3 API_2 Design Guidelines ! ✔ ✔
- 11. 11 11 SwaggerHub is a single source of truth for API development Enables and enforces both internal and industry standards with design-first principles to improve API quality Provides a central repository for API definitions enabling collaboration and feedback across teams within a secure, scalable platform Leverage API definitions through integrations with source control management tools, build tools, API gateways and DevOps environments Faster, Standardized API Design Centralized, Secure API Collaboration Seamless Integrations to optimize SDLC efficiency
- 12. Proprietary & Confidential 12 The SwaggerHub API Ecosystem Organizations, Projects, Teams, Collaborators, Comments, Documentation, Domains, Standards and Governance, Rules, Codegen Gateway Integrations SCM Integrations Registry API Webhooks Maven/Gradle Plug-ins CLI Tool API Gateways SCM Repositories Developer Portals Redoc, Confluence plug-in Developer & Consumer Email Notifications Collaboration Scripts Virtualization Testing SCM Repos & Flat Files Registry API SCM/Actions Pipelines using Registry API Jira, Bamboo, Etc Jenkins Azure DevOps Build Processes Applications Back-end Test, Staging, Production and Sandbox VS Code Server Tags Pull definitions from SwaggerHub
- 13. 13 Demo
- 14. Proprietary & Confidential 14 Thank You Any Questions?