The API Lifecycle Series: Exploring Design-First and Code-First Approaches to API Development
1 like714 views
This document discusses design-first and code-first approaches to API development. It explores how existing services can leverage the OpenAPI Specification (OAS) and the benefits of each approach. Design-first allows for a single source of truth across design, development, testing and documentation. It enables early feedback and iteration. Code-first treats OAS as a byproduct of development and enables existing practices, but requires more customization. The document provides examples of how teams have implemented both approaches using SmartBear tools.
The API Lifecycle Series: Exploring Design-First and Code-First Approaches to API Development
- 1. The API Lifecycle Series – Part 2 Exploring Design-First and Code-First Approaches to API Development
- 2. Housekeeping Proprietary & Confidential Session is being recorded Please post questions to Q+A Open Q+A at end Ronan Trainor Joe Joyce
- 3. The API Lifecycle Series
- 4. 4 Evolving API Development & Testing from Open Source to Pro Tooling • Upgrading your API testing from SoapUI open source to SoapUI Pro • Making your test data more dynamic • Testing in multiple environments • Bringing it all together in a CI/CD pipeline • When to move from open source Swagger tools to SwaggerHub • Generating OAS from an existing microservice • Automatically generate consumer documentation • Getting multiple teams involved Proprietary & Confidential The Story so Far…
- 5. 5 Exploring Design-First and a Code-First Approaches to API Development – Today! • The pros and cons of each approach to API development • How SwaggerHub can be used to facilitate a design-first approach Using the Open API Specification Across the SDLC – July 24th • Discussing the tactical journey of standardizing around Open API • How to scale and enforce design practices across team in your organization Showcasing Teams that Have Put SmartBear Tools into Action – July 31st • Examples of customers that have successfully evolved their API development and testing with SmartBear tools Proprietary & Confidential So what’s next?
- 6. API Design and Development: Code-First
- 7. 7 How can my existing services benefit from OAS? Stage Deploy Build Test Feedback • Existing applications can leverage OAS • Ensure documentation is mapped to code • Leverage design-first principles in future • Annotation libraries • Build plugins • Maven • Gradle • Swagger Inspector • Browser based REST client • Convert requests into swagger • Built in SwaggerHub integration
- 8. 8 Code First - Advantages § Enables development teams do what they do best – write code § OpenAPI is treated as a result of a build, and can be then reused in other scenarios § Documentation § Testing § Virtualization/Mocking § Automated workflows can be built around this § Validate whether or not an API definition has changed § Branching strategy can result in higher test coverage § Versioning is enforced through the build/testing workflow § Ensure that a version doesn’t include breaking changes § Version requirements can be returned to a development team as their { }…
- 9. 9 Code First - Challenges § Requires a complex and highly customized process to automate § Hard to build this in a ‘one size fits all’ manner for larger organizations § May have to be tailored to application/language being developed § ‘Switching’ between tasks becomes commonplace § As developers push to a pipeline, they may move to another task or ticket § If an issue is detected – they will have to stop and return to a previous task § The cost of fixes is higher § In a design first environment, there is contract defining expectations § Feedback that may come back from consumers has to be implemented into code again, as opposed to a light weight document (OpenAPI) { }…
- 10. API Design and Development: Design-First
- 11. 11 How can design-first help? Plan Design BuildTest Deploy Plan Stage Deploy • Plan gets mapped to a high level, technical spec • This contract becomes our ‘truth’ moving forward • Get earlier feedback • Key stakeholders can interact in new ways • Early stage documentation • Functional mock services • Make changes in a fraction of the time • Minimal technical overhead to iterate on previous work • Introduce new workflows • Easy start building a TDD framework • Quickly stand up mock services • Dev + test can work in parallel Feedback
- 12. 12 Design First - Advantages § Single source of truth for § Design § Development § Testing § Operations § Documentation § Create design-driven workflows + processes § Build-in early stage commenting and feedback loop § Share common assets across teams and projects § Cut down on drift between teams § Generate SDKs + stubs as needed § Automate gateway + management platform configuration § Enforce high-level standards over designs § Define assets at an organizational scale § Errors § Models § Security flows § Validate designs against standardization rules and resolve issues before development { }…
- 13. 13 Improving on traditional development • Begin with a high level ‘plan’ • Why are we building the API? • Who will consume / use this service? • What is its scope? What will it serve? • Start writing code to fulfill requirements • Get feedback on early stage (but working) version • We have to consider the ‘technical debt’ of taking on any changes to existing work Plan Build TestFeedback Deploy Plan Build Test Stage Deploy
- 14. 14 Design First - Challenges § Requires ‘buy-in’ across an organization § Siloed teams working in their own ways create more bottlenecks and issues than the process resolves § Communication between code-first and design-first teams can get convoluted § Needs a supporting pipeline or process to realize full value § If the advantages of design-first are still being used manually, § Building and migrating to these types of processes can be a slow process at scale § Maintaining legacy systems and workflows § Not every service will be able to take advantage of OpenAPI § How can we leverage both in parallel? { }…
- 15. 15 Back-end & Front- end Development Testing Design v1.1 Feedback v1.0 Stub OAS Virtual Service Testcase Testcase Production V1.1 Docs V1.1 API 1. The initial requirements are defined for a new version of an API in SwaggerHub 2. Designers, external and internal teams give feedback and ‘sign off’ on changes 3. After approval, code templates can be generated from the design and handed to developers 4. The API design can be consumed by ReadyAPI to automatically generate test cases, virtual services and can be used as an assertion contract 5. As developers complete coding, tests can be brought to validate work based on the contract as part of the build process 6. Documentation in SwaggerHub can be published alongside the new version of the service. The development work, tests and documentation all tie back to the what was approved during the design process What does design-first look like? SDKs
- 16. 16 Questions? Thank You! Join our next session on Wednesday, July 24th Using the OpenAPI Specification Across the SDLC