Lots of people talk about the benefits OpenAPI Specification (OAS) can bring to your documentation and testing efforts, but few people talk about the real complexities involved when you try to scale OpenAPI usage across a large organization. This talk is about how to scale your OAS usage, who should be using OAS, and what concrete steps you can take now to save lots of time later. Finally, we’ll take a look at some real world API growing pains that we see at larger Stoplight customers, and their potential solutions.

1. stoplight.io
OpenAPI at Scale
Marc MacLeod
@marbemac, stoplight.io

2. stoplight.io
The Happy Path
Your resident OpenAPI expert maintains a
detailed + accurate specification file for your
primary API . Reap the rewards with auto
docs, SDKs, mocks, etc.

3. stoplight.io
The Reality
Macro trends like microservices,
containerization, IoT, and serverless are driving
us to a world filled with small, distributed, and
composable parts.

4. stoplight.io
Instead of This

5. stoplight.io
APIs on APIs on APIs

6. stoplight.io
Problems at Scale
Limited Adoption

7. stoplight.io
Problems at Scale
Limited Adoption Stale OpenAPI

8. stoplight.io
Limited Adoption Stale OpenAPI Inconsistent APIs
Problems at Scale
!=

9. stoplight.io

10. stoplight.io

11. stoplight.io

12. stoplight.io
Increasing Adoption: Accessibility
Let’s face it, most people (particularly non-devs)
don’t relish the idea of reading + writing this:

13. stoplight.io
Increasing Adoption: Accessibility
#1: Don’t force everybody to be an OpenAPI expert.
Visual designers like Stoplight or Apicurio can help.
SwaggerUI is great for a read view.

14. stoplight.io
Increasing Adoption: Collaboration
#2: Design first over code first.
This allows non-devs to contribute. OpenAPI specs are as
much a business asset as a development asset.

15. stoplight.io
Increasing Adoption: Collaboration
Get these folks involved!
Technical Writers
Product Managers
QA
Frontend (API Consumers)
Backend
Architects
Business Office

16. stoplight.io
Increasing Adoption: Discoverability
#3: Invest in a centralized registry early on.
A centralized registry helps everybody understand the
value of OpenAPI, and incentivizes word of mouth spread.

17. stoplight.io
Problems at Scale
Limited Adoption Stale OpenAPI Inconsistent APIs
!=

18. stoplight.io
Trust
Your OpenAPI files are your single source of truth.
You never want to ask yourself “Is this OpenAPI file still
accurate?”

19. stoplight.io
Trust
#4: Treat your OpenAPI file like the critical asset it is, and
bake contract tests into your CI process.
Dredd, Pact, and Stoplight’s Prism are all good options
depending on the scenario.

20. stoplight.io
Problems at Scale
Limited Adoption Stale OpenAPI Inconsistent APIs
!=

21. stoplight.io
Automate Consistency
#5: Create an API style guide, and enforce it during the CI
process.
Speccy by Phil Sturgeon is an awesome OpenAPI linter.

22. stoplight.io
Shared Assets
#6: Extract common patterns and models into a shared
asset registry.
Enforce usage of these shared assets where appropriate.

23. stoplight.io
Version From the Start
#7: Bake versioning into all remote URL $refs.

24. stoplight.io
Problems at Scale
Limited Adoption Stale OpenAPI Inconsistent APIs
!=

25. stoplight.io
OpenAPI at Scale
Bake versioning into all URL $refs.
Extract common patterns and models into a shared asset registry.
Create an API style guide, and enforce it during the CI process.
Treat your OpenAPI file like the critical asset it is, and bake contract
tests into your CI process.
Invest in a centralized registry early on.
Design first over code first.
Don’t force everybody to be an OpenAPI expert.#1
#2
#3
#4
#5
#6
#7

26. stoplight.io
The Stoplight Way
Thanks, and we’re hiring!