If you’re developing APIs with the OpenAPI Specification (OAS) and working with the Swagger tools, you’ve likely heard about the importance of adopting a “design first” approach.
The design-first approach advocates for defining your API, using a common standard like OAS, and getting alignment on the design of the API before you start developing the API. In a design-first approach, the API definition acts as the source of truth for your API development and can help streamline processes further along the API lifecycle, including development, testing, documentation, and more.
But adopting a design first approach at scale can also come with challenges. And that’s why we are thrilled to have Cyndi Recker, System Engineer at Viasat, as a presenter at the upcoming SmartBear Connect Conference. In her talk, "Support Rapid Systems Growth with a Design-First Approach,” Cyndi will show you how to reign in far-reaching elements of a system, use a design-first approach to establish a common hierarchical data dictionary, and create reusable components for building system APIs.
We recently had the chance to catch up with Cyndi to learn more about how her organization has adopting a design first approach with SwaggerHub, and to get a preview of her talk at SmartBear Connect.
Read on to find out more.
Without repeating your bio, what’s something you want attendees know about you?
I am passionate about almost everything I do. Both on the job and on my personal time. I have tons of energy, need to burn it all and try to approach every task in life like it is an adventure.
What has been your experience with SmartBear tools like SwaggerHub?
I have used Collaborator (formerly Code Collaborator) in a former role and it worked out great for our team. We were globally distributed; I had team members in San Jose, Arizona, India, and Boston. Collaborator worked well in that it helped us span both time and spoken-language barriers.
Moving on to my experience with SwaggerHub, I have used it for over a year at Viasat where I work as a System Engineer which covers both the hardware and software architecture for the system. The Commercial Mobility System is complex and has communication interfaces that span between aircraft, satellites, and the ground to provide Wi-Fi services to airline passengers.
Like many architectures, the system has evolved over time and anomalies have surfaced causing problems on interfaces. There are many system-to-system messages where information obtained from an origination point, like portal, takes several hops before reaching its final destination. For example, an object, such as aircraft, had been created numerous times with different names and attributes. The same is true for a MAC Address.
In the past, I worked on a military program for space-based communications where I hand-crafted a data dictionary and a requirements traceability tool because nothing was available on the market to fit our needs. Fast forward a few years and I am at Viasat, facing a similar tool need.
So, when I stepped into this role over a year ago we were hopeful that the SwaggerHub domain technology could help us solve some problems. Although not a perfect fit, it has enabled us to maintain our current system while working on new designs. We can use a common set of data entities and messages as a foundation to build up a hierarchical model. SwaggerHub is solving some problems for our business, most importantly it’s helping us wrangle our data.
To summarize, I think the advantages are:
First, using the domains brings you to a point where you can organize your data so that you get the most bang for your buck in terms of knowing where the impact is for all your change.
Second, with your SwaggerHub tool you can click on a reference within an API that will navigate to the back-referenced definition in another document. This helps you identify APIs and domains where the entity used. In the future, I would like to see a feature that would allow me to click on a definition and provide a summary of all of the APIs where a data entity is used.
And lastly, SwaggerHub provides a way to collaborate with various team members who are in different roles such as architects, developers, test, QA, etc. who can all touch the information and keep a project moving through the pipeline.
When did Viasat move to a Design-First Approach?
I think Viasat’s always had a Design-First Approach but not great tool enablement to support architecture and design tasks.
Who do you think would most benefit from attending your talk?
I think the session will be good for many different participants. I will show how domains are helpful in bringing together multiple types of interfaces from portal UX/UI through lower level system-to-system messages. I also believe it will be good for people who are needing to scale their system for growth with APIs that contain common data as well as those who use Swagger.io and have not tried SwaggerHub.
What are you most looking forward to about SmartBear Connect?
I’m really interested in two things: one is the training and learning about some of the other products, and two is meeting some of my peers and maybe see how they solve some other problems that I have not thought my way out of yet.
If you are looking to meet with peers to talk about similar problems, are there any questions that you’re wrangling that you’d like to talk about with them?
One of the problems that I have with the Design-First Approach using SwaggerHub is really getting to the point of code generation. You can’t really get into full scale maturity with code generation, you still have to hand-touch code. So, I would be interested in discussing the topic of code generation from SwaggerHub. What I would ask would be, “Have you been successful?” And if so, “How do you get past to being able to step out the code?”
I’d also be very interested in taking our APIs through automated testing and seeing how some of that works since we haven’t done it yet at Viasat.
How do you currently test your APIs?
We have a combination of in-house testing and use Soap UI in some cases. Recently our organization adopted a DevOps approach where testing is part of the team. Some teams are looking at the ReadyAPI solution using SoapUI Pro and LoadUI Pro. I am looking forward to getting a closer look at those products at SmartBear Connect in the training sessions.
This October 29th & 30th Cyndi will be ready to talk to you at SmartBear Connect. She’s really looking forward to coming to Boston and meeting you. Want to join us at SmartBear Connect? Use the promo code "SwaggerHub_Connect18" to save $100 on your ticket.