The idea of designing an API first, then having both the publishing developer teams and consuming client developer teams do their work in parallel is a pattern that the standards & tooling of the Open API ecosystem make worth considering. However, this approach is not without its challenges especially when it comes to governance and communication. This session will present a real-world case study where this approach was executed successfully, going over how the work, teams, and deliverables were structured and presenting lessons learned that will be useful to anyone else considering this working model.

2. Contract-first API Development:
A Case Study in Parallel API
Publishing & Consumption
Chris Busse, APIvista

3. Contract-first API Development
Chris Busse | @busse | #apistrat

4. Contract-first API Development
Chris Busse | @busse | #apistrat
Karl

5. Contract-first API Development
Chris Busse | @busse | #apistrat
One day my Web Designer friend Lisa called me
• She had a new client, TidalScale, and needed help
building a functional demo based on her UI design
• The front-end would be Angular
• Very advanced & capable dev team on a fast moving
project…
“They said if I can tell them what APIs I need,
they’ll build them!”

6. Contract-first API Development
Chris Busse | @busse | #apistrat
Let’s use the Open API
Specification and design with
a Contract-first approach.
Everything will be
AWESOME!

7. Contract-first API Development
Chris Busse | @busse | #apistrat
The Team
Lisa
Designer
Chuck
Product Manager
Leon
Back-end Dev
James
Front-end Dev
…and Chris (me), wrangling the API Spec!

8. Contract-first API Development
Chris Busse | @busse | #apistrat
Started with a paper prototype UI to determine data model

9. Contract-first API Development
Chris Busse | @busse | #apistrat
What were we defining an API for?

10. Contract-first API Development
Chris Busse | @busse | #apistrat
“I wrote up this JSON blob..”
• This model was derived from the paper prototype
• ~300 lines, 8 levels deep, representing their entire architecture
• This was a very important artifact – it represented well-
organized, thought out and a unified view from the Product
and Back-End Dev teams
• In an Enterprise, we’d call this “Governance” and a lot of
effort is put into this process

11. Contract-first API Development
Chris Busse | @busse | #apistrat
Reorganized the JSON blob into Open API Spec

12. Contract-first API Development
Chris Busse | @busse | #apistrat
Back-end Dev built Mock Services in Go
• Mock Service backed the demo and were easy to begin
populating with real data as it became available
• Willingness to expose this to whitelisted IPs enabled
better distributed development & “Try It Out”
• This could be considered “throw away” work by some,
but it was critical to getting the Front-end developer
working in parallel

13. Contract-first API Development
Chris Busse | @busse | #apistrat
Front-end Dev used the Spec as source of truth

14. Contract-first API Development
Chris Busse | @busse | #apistrat
Now we were doing parallel development
Back-end Dev
- Validate Data Structures
- Create Initial Mock Services
- Make them functional
Front-end Dev
- Build first from Spec
- Test against Mock Services
- Provide validation and feedback
Product Team
Sees the demo in action sooner
Able to facilitate product feedback quicker

15. Contract-first API Development
Chris Busse | @busse | #apistrat
Used Spec + GitHub to Organize a Feedback Loop
Parallel
Development
Collaborate
Modify Spec
After a few iterations the
TidalScale team was
making Spec edits too

16. Contract-first API Development
Chris Busse | @busse | #apistrat
This enabled very rapid iteration
• We versioned the spec (arguably a misuse of that field)
• Kept a CHANGELOG.md in the repo to make changes
human-readable
• Used Semantic-ish Versioning (http://semver.org/)

17. Contract-first API Development
Chris Busse | @busse | #apistrat
Moving fast!
• Communicating in code
• Spotting issues with the spec quickly
• Realtime collaboration was happening

18. Contract-first API Development
Chris Busse | @busse | #apistrat
“Now we need to document the WebSockets!”
• The overall solution architecture used WebSockets in addition to REST
• We discovered that we wanted all-encompassing developer
documentation across different types of APIs, which went beyond what
Open API Spec/Swagger supported
• Open API Spec is really about REST - How as practitioners do we
handle a mix of WebSockets, GraphQL, etc in the Developer
Documentation Experience?

19. Contract-first API Development
Chris Busse | @busse | #apistrat
“Now we want to publish as ASCIIDOC…”
• “The industry” generally accepts that “online interactive”
documentation is “what developers want”
• Client & business needs may dictate other channels
• OAS’s ecosystem was very helpful here – someone had already
built a tool that simplified ASCIIDOC conversion

20. Contract-first API Development
Chris Busse | @busse | #apistrat
We shipped the demo on
time and it achieved its
goals!
Everything is AWESOME!

21. Contract-first API Development
Chris Busse | @busse | #apistrat
General Takeaways
1. Good communication is often the best tool to solve a
problem
2. Governance to align stakeholders pays dividends (and
helps create a positive SNR for Devs)
3. There’s more than one way to version – do what’s best
for you – it’s about effectively communicating change
4. Not every API is REST - understand the limitations of
any tooling you bring in to your solution

22. Contract-first API Development
Chris Busse | @busse | #apistrat
Contract-first Parallel Development
• Can enable rapid innovation and change
• Create a page to be the “same page” – Open API Spec
was that for us – align everyone on the “contract’
• There must be a give & get from both sides
– Back End: Willing to spend time building Mocks
– Front End: Willingness to change when data
structures change

23. Contract-first API Development
Chris Busse | @busse | #apistrat
Sometimes a technical problem is really
a communication problem in disguise.

24. Contract-first API Development
Chris Busse | @busse | #apistrat
Thank you!
Chris Busse
chris.busse@apivista.com
http://apivista.com
@busse
http://busse.io