Learn about the benefits of API Contract as Code from Ted Epstein, Founder & CEO of RepreZen.

1. TED EPSTEIN, FOUNDER & CEO | Ted.Epstein@RepreZen.com
1COPYRIGHT © 2017, MODELSOLV, INC. | ALL RIGHTS RESERVED.
API Contract as Code
Rapid Development with OpenAPI

2. First Swagger Value Proposition
• Keep your API docs in sync with implementation!
… and look cool
doing it!
COPYRIGHT © 2017, MODELSOLV, INC. | ALL RIGHTS RESERVED. 2

3. Code-First
• Or “API Code-as-Contract”
COPYRIGHT © 2017, MODELSOLV, INC. | ALL RIGHTS RESERVED. 3

4. So why not all code, all the time?
• Not Cross-functional team-friendly
◦ Coders aren’t always the best communicators.
◦ Tech writers don’t want to maintain embedded code comments
(and you may not want them to).
• De-emphasizes API design
◦ Outside-in design, from the user’s perspective
◦ As a distinct process
◦ Leveraging available tools for docs, mocking, testing, etc.
◦ Conscious, collaborative focus to API design quality
COPYRIGHT © 2017, MODELSOLV, INC. | ALL RIGHTS RESERVED. 4

5. But there’s another reason…
• Leverage
◦ Higher productivity
◦ Greater expressive power
• An OpenAPI Description is code!
◦ High focus, high abstraction
◦ Generated code can be a scaffold to get started quickly…
◦ … and it can be first-class code.
COPYRIGHT © 2017, MODELSOLV, INC. | ALL RIGHTS RESERVED. 5

6. COPYRIGHT © 2017, MODELSOLV, INC. | ALL RIGHTS RESERVED. 6
API Contract-As-Code
Development Workflow

7. COPYRIGHT © 2017, MODELSOLV, INC. | ALL RIGHTS RESERVED. 7
API Contract-As-Code
Development Workflow

8. COPYRIGHT © 2017, MODELSOLV, INC. | ALL RIGHTS RESERVED. 8
API Contract-As-Code
Development Workflow

9. COPYRIGHT © 2017, MODELSOLV, INC. | ALL RIGHTS RESERVED. 9
API Contract-As-Code
Development Workflow

10. COPYRIGHT © 2017, MODELSOLV, INC. | ALL RIGHTS RESERVED. 10
API Contract-As-Code
Development Workflow

11. COPYRIGHT © 2017, MODELSOLV, INC. | ALL RIGHTS RESERVED. 11
API Contract-As-Code
Development Workflow

12. COPYRIGHT © 2017, MODELSOLV, INC. | ALL RIGHTS RESERVED. 12
API Contract-As-Code
Development Workflow

13. Demo
COPYRIGHT © 2017, MODELSOLV, INC. | ALL RIGHTS RESERVED. 13

14. Achieving Separation
• “Write-once” codegen for implementation
• Delegation
• Interface / Implementation
• Abstract Base Class / Concrete Implementation
• Dependency Injection
• Dynamic merge (e.g. C# partial classes)
COPYRIGHT © 2017, MODELSOLV, INC. | ALL RIGHTS RESERVED. 14

15. Project Layout
• All in one project
• One project for API spec, generate into
second project for implementation
• Generated library
COPYRIGHT © 2017, MODELSOLV, INC. | ALL RIGHTS RESERVED. 15

16. Validating Implementation vs. Spec
Implementation Completeness:
“Every method is implemented”
◦ Use static typing when available
◦ Use generated or dynamic unit tests for
dynamic languages
Specification Completeness
“Every method implemented is in the
specification”
◦ Harder to enforce, but easy to prevent.
◦ Static code analysis or reflective tests could
be useful
Correctness
Methods implement the contract
(mechanics)
Methods have the expected outcome
(semantics)
◦ Use testing tools or frameworks, same as as
you would with code-first
COPYRIGHT © 2017, MODELSOLV, INC. | ALL RIGHTS RESERVED. 16

17. OpenAPI 3.0 - More Descriptive Power,
New Possibilities…-
• Links
• Callbacks
• oneOf / anyOf Schemas
• Component Model
COPYRIGHT © 2017, MODELSOLV, INC. | ALL RIGHTS RESERVED. 17