Full transcript
0:03[Music]
0:10well good morning everyone um my name is
0:12Brett Bush and today I'm going to be
0:14sharing the story of how our team
0:16leveraged open API specification testing
0:19to adopt an apid driven development
0:21model and as a result seamlessly scale
0:24our developer relations program let
0:27me here we go uh before we dive in I'll
0:31share a bit about myself and my company
0:33again I'm Brett Bush I work at late
0:35which is based in Chicago Illinois uh
0:38I'm a senior software engineer and over
0:40the last two years I've been leading and
0:42building out our developer relations
0:44program uh my background has been in
0:46apis and SDK development which
0:48ultimately led me to developer
0:50relations uh and in leading our
0:52developer relations program I I've
0:55become involved with open API
0:57specifications API First Development and
0:59AP API documentation as far as logic
1:02gate we're in the industry of GRC
1:04governance risk and compliance and we
1:06deliver a holistic no codc platform so
1:09organizations can proactively understand
1:12manage and mitigate their everchanging
1:14risk and compliance Landscapes uh we
1:16have a SAS platform called the risk
1:18cloud and as a SAS platform we provide
1:21apis for building out custom
1:23Integrations hence the need for a
1:25developer relations program to begin our
1:28journey to an API first approach Ro
1:31however shifting to an API first model
1:33can be an uphill climb according to
1:36postman's 2023 state of the API report
1:3975% of participants agree that
1:42developers at API first companies are
1:44more productive so there's a large
1:46incentive to adopt an API first model
1:49however only 11% ranked themselves as
1:53highly API first so how did these
1:55companies in the 75% that acknowledge
1:58the productivity benefits of an API
2:00first model become API first themselves
2:04well like many software development
2:06answers go it depends every company is
2:09at a different stage in their journey
2:10and starting from a different place
2:12which leads to our journey our team's
2:14API started out as code first where the
2:17codebase of our API used API
2:19documentation generation libraries to
2:21generate our open API specification from
2:24the codebase which could in turn be used
2:26to generate our API documentation the
2:29code was developed before the API with
2:31our open API specification and
2:34documentation essentially being
2:36improvised off of the
2:37codebase however like many organizations
2:40we wanted to shift to API first where
2:42the API is developed before the code for
2:46this it meant putting the open API
2:48specification as the central source of
2:50Truth informing the design of the
2:52codebase as well however we soon
2:54realized that the codebase could change
2:57independently of the API documentation
2:59causing a disconnect between the two in
3:02addition by not leveraging the API
3:04documentation libraries in our codebase
3:07to generate the open API specification
3:09we lost a fair amount of convenience
3:11that we had before what we desired
3:14wasn't just a code first approach or an
3:16API first approach but what we would
3:18call an apid driven approach where
3:21similar to API first the API is
3:23developed before the code however
3:25alignment is guaranteed between the API
3:28and the code as well so from our
3:30starting point of code first how do we
3:32manage the tradeoffs of transitioning
3:34our open API specification from being
3:37improvised from our code base to
3:38becoming aligned and an aligned and
3:41Central source of Truth across our
3:42entire development process with our
3:44starting point being improvised let's
3:47Envision this in another improvisational
3:49setting improvised Jazz let's say we are
3:53in a jazz band and here's our
3:54performance process for our band our
3:56musicians are the source of our music
3:59the performance of our music is the
4:00production and the sheet music that is
4:02transcribed from the performance is the
4:04output along with any variations of the
4:07sheet music such as including other
4:09musicians to perform the piece or
4:11exporting the sheet music to a digital
4:13setting we're happy as a jazz band with
4:15the existing qualities of our
4:17performance process however our goal is
4:19that we want to share our music with the
4:21world through our sheet music which
4:23we're currently unable to do however we
4:25can pres how can we preserve the
4:28benefits we currently have as an
4:30improvised jazz band while also
4:32achieving our goals let's walk through
4:34each quality of our performance process
4:36and see the tradeoffs that we'll need to
4:38make the First Quality that we enjoy as
4:40a jazz band is that our performance is
4:42direct being direct means that there's
4:44convenience in how the musicians create
4:46the performance and that the performance
4:48is transcribed directly from the sheet
4:50music next our performance is flexible
4:53if a musician notices that the
4:55performance would be better if their
4:56part were louder or softer this would
4:59reflect in the transcribed sheet music
5:01of the performance and finally as a jazz
5:03band we like knowing that the sheet
5:05music that is transcribed from the
5:07performance will always be accurate
5:09provided of course that we have a very
5:11talented
5:12transcriptionist however as a jazz band
5:15there's some room for improvement for
5:16instance our performance process does
5:18not guarantee a singular sheet uh a
5:21singular piece of sheet music our
5:24musicians can perform any number of
5:26performances with each producing
5:28slightly different variations of the
5:29sheet music additionally our performance
5:32process does not have sheet music
5:34available at any given time as a full
5:37performance and transcription is
5:39necessary before sheet music is
5:41available with generating sheet music
5:43being an inconvenient and time-consuming
5:45task this impacts our ability to share
5:48the sheet music with other musicians or
5:50export it to a digital setting and
5:52finally if a musician unintentionally
5:54makes a mistake this mistake would be
5:56recorded into the final sheet music
5:58which would have a ripple effect to
6:00other musicians performing the piece or
6:02exporting it digitally so with these
6:05goals in mind what's one step we could
6:07take to making this sheet music and
6:09performance process more singular
6:11available and intentional well currently
6:14the performance is developed before the
6:16sheet music so let's try flipping it
6:18around where the sheet music is
6:20developed before the
6:21performance now that we've written the
6:23sheet music out first and have given it
6:25to our musicians we achieve our goals of
6:28Singularity and avail ility by having a
6:30single source of Truth on hand however
6:33the performance of the sheet music may
6:35still not be intentional given that the
6:37musicians can still make mistakes with
6:39the possibility of mistakes that also
6:41means there's no guarantee that the
6:43sheet music The Musicians have and the
6:45sheet music transcribed from the
6:46performance are the same how can we
6:49ensure that the musicians perform the
6:50music as intended without making any
6:52mistakes well we could replace all the
6:55musicians with robots with robots
6:58performing the music we achieve all of
7:00our goals we have a single source of
7:02sheet music the sheet music is composed
7:04ahead of time and is readily available
7:06and we can guarantee that the sheet
7:07music will always be performed as
7:09intended since again it's being
7:11performed by
7:12robots however in replacing human
7:14musicians with robots we lose a level of
7:17musicality and which ultimately affects
7:20the flexibility of the performance that
7:21we had before for example if we want a
7:24part of the music to be louder or softer
7:26the robot musician would disregard any
7:28level of Nuance in favor of following
7:30the score note for note that means that
7:33any musicality details and Nuance would
7:35need to be written directly into the
7:36sheet music ahead of time which could
7:38become very timeconsuming and complex so
7:41let's take a step back from robots and
7:43reflect on where we are we want to have
7:45our sheet music composed and available
7:47and we have a feeling it's a step in the
7:49right direction but we need something to
7:51align the sheet music across our whole
7:53Performance Cycle well picturing this
7:55Group performing on a stage there's a
7:57key member that it feels like we're
7:58missing
8:00a conductor a conductor has the ability
8:03to internally transcribe the sheet music
8:05from the performance in real time and
8:07verifies its alignment with their golden
8:09copy of the sheet music called the score
8:12now the sheet music is developed before
8:13the performance but alignment is also
8:16guaranteed between the performance and
8:18the sheet music it's direct and that
8:20it's convenient for the uh to perform
8:22for the conductor who can transcribe in
8:24real time it's flexible where if the
8:26musician notices that the performance
8:28would be better if their part were
8:29louder or softer the conductor would
8:31notice this difference but can act as a
8:34mediator to update the score to reflect
8:36the positive change the performance will
8:38also always be aligned with the
8:40conductor's transcription and in turn
8:42the score itself there's also a singular
8:45source of Truth for the sheet music as
8:47represented by the score the score
8:49itself is also available at any time for
8:52either sharing with another musici or
8:54exporting digitally additionally it's
8:56circularly available as sheet music for
8:58the performing musicians themselves and
9:01while the conductor serves as a flexible
9:03mediator for productive changes if
9:05there's unintentional mistakes the
9:07conductor can detect them and indicate
9:09that should they should be addressed
9:11keeping the golden copy of the score
9:13preserved as intended with our goals of
9:16availability Singularity and
9:17intentionality in mind we've come a long
9:19way from our original process of
9:21improvised Jazz from a
9:22performance-driven approach to a score
9:24driven approach with the help of our
9:26conductor and score now you may be
9:29asking yourself what does any of this
9:30have to do with apis and that's a good
9:33question well while we've walked the
9:35through the Journey of this jazz band
9:37adopting a score driven approach through
9:39their conductor and score this is the
9:41same Journey our team took when adopting
9:43an API driven approach however instead
9:45of a source of musicians a production of
9:48our performance and an output of sheet
9:50music this was actually our code first
9:52approach where the code was developed
9:54before the API instead of musicians our
9:57source is API code instead of our
9:59performance our production is the live
10:01API in production and instead of sheet
10:04music our output is an open API
10:06specification with the ability to export
10:08to tools like API documentation or
10:10Postman so with this shift let's recap
10:13what we tried with the Jazz Band to
10:15achieve the goal of having a singular
10:17available and intentional open API
10:19specification to serve as the source of
10:21Truth in our development process we
10:23tried API first quite literally by
10:26developing the API design first and
10:28having it inform the API code like sheet
10:30music and for a time this gave us a
10:32singular and available copy of what we
10:34wanted to develop however just as with
10:37our jazz band intentionality was still
10:39lacking and as code is updated although
10:42following an open API specification When
10:44developing is a great guide there's
10:46nothing preventing unintended API
10:48changes from making it into production
10:50so again how can we ensure that the open
10:52API specification is honored taking
10:55inspiration from our robot approach from
10:57earlier we could generate the API code
10:59from the open API specification using a
11:02code generator tool this ensures that
11:04our a goal of intentionality ISS met
11:07since the production API and generated
11:09open API specification will always
11:12reflect that core open API
11:14specification however given that we're a
11:16SAS platform generating our API entirely
11:20from an API specification would cost us
11:23the flexibility of our application's
11:25business logic meaning new features
11:27would need to be built entirely from
11:29within the open API specification as
11:31opposed to in a code base and while it
11:34would be really cool to replicate the
11:36entire Nuance of our web application
11:38with open API extension properties it
11:41would unfortunately be very timec
11:42consuming and complex so here we are
11:45stepping back to API first trying to
11:47balance the tradeoffs of a code first
11:49approach and an API first approach we
11:51need to call our friend the conductor
11:54and in this case our conductor and score
11:56is instead an integration test and a
11:58main static and golden copy of our open
12:01API specification just as the conductor
12:04served as a mediator and validator
12:06between the performed sheet music and
12:08the score the integration test validates
12:10alignment between the generated open API
12:13specification and the main open API
12:15specification and as the score served as
12:18a source of Truth for the sheet music
12:20the main open API specification serves
12:22as a static per commit reference of the
12:25API at any given moment in time with
12:28this approach we balance code first and
12:30API first together where the API is
12:32developed before the code and Alignment
12:35is guaranteed between them thanks to our
12:37integration test let's take a closer
12:39look at the integration test and the
12:41main open API specification our main
12:44open API specification lives in our
12:46codebase alongside our production code
12:48it's a static file so there's no need to
12:50generate it since it doesn't require
12:52generation it's also available for
12:54reference or testing at any given time
12:56and thanks to our open API test it
12:59accurately reflects the state of the API
13:01in the code base at any given time to
13:03the git
13:04commit when we zoom into the code of the
13:07test the open API test is only a few
13:09steps and could be refactored into a
13:11variety of code languages that have open
13:14API libraries available the test here is
13:16written in cotlin and here are some of
13:19the steps of what it does first it
13:20creates an open API object based off the
13:23static main open API file in our
13:25codebase next it creates a second open
13:28API object from the open API file
13:31generated from our API in this example
13:34we're getting this file from an endpoint
13:35provided by our API documentation
13:37library then we test both open API
13:41objects for equality which depending on
13:43the language and Library can sometimes
13:45just be done with a default equals
13:46symbol or a do equals method or you can
13:49test certain sections of the open API
13:51specification individually too a bonus
13:54while you're testing this is you're able
13:56to test things in the open API
13:58specifications for formatting this way
14:00you can ensure that every property is
14:02documented and that API design standards
14:05are met for things like camel case
14:06versus Kebab case that's not the only
14:09bonus though with the existence of this
14:12a test makes any API first change to the
14:15open API specification an act of test
14:18driven development if you're familiar
14:21with test driven development it's a
14:23development model where tests are
14:24developed before the code similarly API
14:27first is where the AP API is developed
14:29before the codee and with both the API
14:32and our open API test developed before
14:35code is written our API driven approach
14:37can be thought of as a combination
14:39between these two models as a result
14:41we're able to gain the benefits of test
14:43driven development and that we can
14:45update the open API specification to
14:47drive the implementation of the API for
14:50example in the screenshot here a
14:52developer adding a new property can add
14:54all the details of uh an API change to
14:57the open API specification prior to
15:00development then make the code changes
15:02to meet this definition this certainly
15:04doesn't replace functional testing but
15:06it deserve but it serves as a design
15:09test to ensure that your code changes
15:11are aligned directly to what is planned
15:13for the design of the API if the open
15:16API test detects an unexpected change
15:18that occurred during development the
15:20test will fail however you now have the
15:23flexibility to determine whether you
15:25should update the code to fit that
15:27specification or whether the main
15:29specification itself should be updated
15:31similar to our conductor updating the
15:33main score based on constructive
15:35feedback from a musician with our main
15:38open API specification at the center of
15:40our development process we've been able
15:42to leverage it in so many new exciting
15:44ways we've improved our API
15:46documentation using open- Source tooling
15:48to generate it from our open API
15:51specification we've release the open API
15:53specification itself on GitHub to share
15:56with customers the API design can be
15:58find ahead of development with our apid
16:01driven
16:02approach with the test in place we can
16:04also detect breaking changes in our API
16:07early before merging them into
16:09production and on a uh individual merge
16:12request for code review you can see all
16:14the API changes very clearly on the open
16:18API specification file itself we've also
16:21gained the ability to share accurate
16:22release notes by using open source tools
16:25to take a diff between the open API
16:27specifications in our current version
16:29and the previous version of our releases
16:31and finally we've used the open API
16:33specification as the basis for our
16:35Postman collection to share with
16:36customers so what's next we're planning
16:39to leverage this open API specification
16:41to build client sdks we're looking to
16:43scale out API driven development into
16:45our feature planning and ticket planning
16:47uh to include on specific tickets to
16:50serve as a guide for development and
16:52while this work a lot of this work was
16:54focused on our public apis we'd love to
16:56see these benefits internally as well so
16:58we're exploring how we can leverage this
17:00model for our internal API practices too
17:03overall here are the takeaways that we
17:04learned API first is a journey not a
17:07destination and it's a series of
17:08trade-offs from where you're at and how
17:10you're going to continue to prioritize
17:12API design in your development process
17:15next open API specifications go a long
17:17way and formalizing one as a single
17:19source of Truth at any given time takes
17:21it even further allowing you to unlock a
17:24lot of new opportunities however
17:27building out a process to have this
17:28single source of Truth can be a
17:30challenge and in our case the solution
17:32was an API driven development model and
17:34on that note our final takeaway uh is
17:36the discovery of our API driven
17:38development model which combined a test
17:40driven development and an API first
17:42approach allowing us to Leverage The
17:44Best of code first and API First
17:45Development so once again I'm Brett Bush
17:48uh if you're interested in chatting more
17:49about API driven development devil apis
17:51in general you can connect with me on
17:53LinkedIn my website or anytime during
17:55this conference and if you're interested
17:57in leveraging our risk Cloud platform to
17:59help with managing your cyber risk
18:00programs check out logic gate as well
18:02that's all for me thanks so
18:04[Applause]
18:12much