The document discusses effective API lifecycle management using the OpenAPI Specification (OAS). It describes the stages of an API lifecycle including design, development, testing, deployment and versioning. It identifies challenges around collaboration, documentation, security and testing. It recommends using OAS to drive quality at all stages and details how OAS can help with versioning, automation, change management, extensibility, reusability, compatibility and verifiability. The key takeaways are to not reinvent the wheel, prepare for changes, have a process, and put quality at the center of the API lifecycle.
2. 2
Introduction
Solutions Engineer with SmartBear
Experience in web development, software
testing and operations
Current focus is on API design and testing
tools
From Galway in the west of Ireland
Joe Joyce
4. 4
The OpenAPI Specification
OpenAPI Specification (formerly Swagger Specification) is an API
description format for REST APIs. An OpenAPI file allows you to
describe your entire API:
Available endpoints
Operations on each endpoint
Operation parameters
Authentication methods
Contact information, license, terms of use and other information.
(You can find it on GitHub!)
{ }…
10. Documentation
• Coupling the technical specification
with the user documentation
• Ensuring the documentation is updated
as soon as the specification changes
• Make it easy for developers to consume
the documentation
11. Security
• Choosing a protocol
• Integrating your OAS with a gateway
• Controlling visibility of your API
12. Testing
• Bringing API testing into your existing
functional testing framework
• Choosing a toolset
• Ensure test coverage (all endpoints /
operations have test cases built
against them)
13. How Do We Tackle These Challenges?
(Hint: don’t reinvent the wheel!)
14. 14
Embedding quality in your API lifecycle with the OAS
• Use the OAS to drive quality at
various stages
• Make quality a priority and not
an afterthought
15. 15
A good OAS can help to
ensure good API hygiene…
• Steps you can take to ensure
you’re producing healthy APIs
16. 16
Versioning
• Software needs version control, so do API specifications.
• When endpoints / resources change
• Security changes
• API deprecation
17. 17
Automation
• Deployment of a new endpoint / resource path
• Creation of test cases
• Generating implementation code
• Updating proxies on our API gateways
18. 18
Change Management
• Things will change! So have a plan.
• New endpoints might be needed,
new responses, new security
requirements…
• Having a process is always preferable
to no process
19. 19
Extensibility
• With a design first approach, changes happen at
the specification level first
• This allows teams to understand how changes
might affect the API
• It also makes it cheaper and quicker to rollback
21. 21
Compatibility
• The main goal of APIs is to allow
systems to communicate with each
other
• This means integration testing is
hugely important
• A robust API definition helps with this
22. 22
Verifiability
• A good software system should
be testable
• Testability starts at the design
phase
• This means implementation is
more likely to match
specification
24. 24
Key Takeaways
• Don’t reinvent the wheel
• Don’t get caught by surprise!
• Changes will happen, so be
prepared to deal with them
• Having a process is better than
not having one
As APIs continue to become a core focus of organizations, ensuring quality is a major factor at every stage, while also speeding up development. To embrace this reality, we must develop pragmatic approaches for closed-loop processes, outcome-oriented development, and effective change management techniques to deliver on the promise of APIs. Joe Joyce, Solution Engineer at SmartBear will discuss these modern issues and outline impactful approaches for you to resolve the daily challenges they present.
Planning and Design
Who are the users of the API?
What functions should we expose?
Implementation and Testing
What protocol(s) should we use?
What languages and frameworks should we build it with?
How do we test it?
Deployment
What platform should we deploy our API on?
What management platform? Do we need a gateway?
Versioning and Deprecation
What should constitute a new version of an API?
How do we communicate a deprecated API?
https://pdfs.semanticscholar.org/9b18/aff5a26446e2c179170f6888856e62954e76.pdf
A good OpenAPI Specification can be used to drive quality at various points of your lifecycle.
This means API quality is the main focus of teams from the very beginning of a API development, and keeps it at the center of all subsequent activities.
https://pdfs.semanticscholar.org/9b18/aff5a26446e2c179170f6888856e62954e76.pdf
It means taking steps to ensure you’re producing healthy APIs
We’re already familiar with a lot of these in a general software quality sense; APIs shouldn’t be any different!
When should we create a new version of an API specification?
What can we automate using our OAS as a trigger?
https://medium.com/good-api/api-change-management-2fe5bba32e9b
Once your OAS leave design phase, other teams are going have inputs. Things will change!
New endpoints might be needed, new responses, new security requirements
You should ensure that we have processes in place to handles these changes. (Comments, notifications, review processes etc.)
“…a system’s ability to have new functionality extended, in which the system’s internal structure and data flow are minimally or not affected.”
Defining these reusable components at the specification level makes it easier to ensure implementations are consistent
can help with this as it can be used in test case design and implementation.
s
An OAS specification can be used to model test cases on based on expected responses, accepted inputs and data types, security flows etc.