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.

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