apidays LIVE Australia - Building Business Ecosystems
Definition-Driven API Development: Streamlining your API Development with OAS
Martin McDonagh, Lead Solutions Architect at SmartBear
3. 3
API First Approach
Client A Client B Client C
API API API
Mock Mock Mock
Implementation Implementation Implementation
Frontend Developers
Backend Developers
The API First approach involves having your APIs as the first and
primary element of your product and service strategy,
Database
4. 4
Definition Driven API development advocates for designing the API’s contract first
before any other lifecycle operation
The Definition Driven Answer
Drives
Implementation Maintenance Consumption
5. 5
• A definition is a framework for describing APIs
• Machine and human readable
• Language agnostic
A Common Vocabulary
The Open API Specification (OAS) is the world’s standard
for defining RESTful APIs
6. 6
Reduced interdependencies, allow teams to work at their own pace
Fast development and delivery
Easier expansion to different interfaces, clients and views
Developer friendly services to build ecosystems and platforms
Advantages of Definition Driven Development
Faster Development
New Revenue
Channels and Growth
7. 7
OAS opens a world of possibilities
Mocking
Design
Clients
Deployment/Runtime Documentation
Virtualization
Testing
Implementation
Prototyping
Object reuse, Callbacks
etc.
Generated client libraries
Security, Usage policies,
Monitoring, Caching, etc.
Developer portals, code
samples, User guides, etc.
Functional/Runtime simulations
Functional, Security, Load, etc.
Generated server code/artifacts
11. 11
Virtualization accurately mimics/simulates behaviour of components that are unavailable or
difficult to access during software development and beyond.
Examples of components that can be virtualized:
Service Virtualization
Devices Databases API Network
12. 12
Virtualization from the Definition
Virtualization
• Developers
• Testers
• Other Stakeholders
Consumer
Development
14. 14
The OAS definition allows you to generate server stubs and client SDKs directly from the definition
Code-Generation from the Definition
Developer
Consumer
Codegeneration
SDK
16. 16
Testing from the Definition
The OAS definition allows you to generate test cases directly from the contract
Tester
TestAPI Testing
tool
Refactored
Refactored
Test cases
17. 17
• OpenAPI Specification is machine and human readable
• OAS allows for parallel development
• OAS can be driven across the full API Lifecycle
• Virtualization allows to build an advanced mock from the OAS definition that is dynamic
• It is also possible to build a test in minutes directly from the OAS definition using Open Source or
Professional API testing tools
Summary
OpenAPI Specification (formerly Swagger Specification) is an API description format for REST APIs.
An API-first approach means that for any given development project, your APIs are treated as “first-class citizens.”
That everything about a project revolves around the idea that the end product will be consumed by mobile devices, and that APIs will be consumed by client applications.
An API-first approach involves developing APIs that are consistent and reusable, which can be accomplished by using an API description language to establish a contract for how the API is supposed to behave.
The API design that is stubbed out can be used by front-end and backend devs
APIs functionality can be stubbed out.
Minimizing dependencies between backend and front end devs
API backend stubbed out
Putting yourself in the end-consumers shoes
Design the api interface first
Remove dependencies
Implementation logic
Create a great consumer experience
Common framework of thinking
Technical writers, developers, Architects
Reduces issues with inefficiencies and teams
Keeps everything in sync
Source of truth – integrate with workflows and tools
- Jenkins/GitHub etc for workflow
Starting from the API design
Fits in well with mocking
Expand to front clients
Faster = reduced interdependencies between teams
Clients = not constrained by architecture with design first
Put yourself in the consumers shoes and build a great experience for building ecosystems
Early feedback and speed
Google Maps / Rate limits
Load Testing against virtual service
Mimic the behavior of google maps
Hand off to front end developers
- Clone and create advanced scenarios
- Shared to consumers internally and externally
- Beta feedback?
- Advance development processes
Sandbox
Advantages:
Reduces dependency between teams (front end/backend)
Enables parallel development
Faster prototyping (startup)
Advantages of code gen:
No wasting time of boiler plate code
Faster prototyping
Out of the box SDK generation for easy consumption
Developer focuses on business logic
Generate SDKs for a better consumer experience
Advantages of testing from the definition:
Reduce time to market by generating quick tests
Easily tie back to development process and refactor changes (minimize confusion)
Mitigate risk (Testing before production)