June 29, 2023 • 39 mins
As programmers and global travelers, we understand the importance of being well-versed in multiple languages. However, there's one language that holds a special place in our hearts: the language of API Design.
It's a skill that requires a delicate balance of consistency, developer experience, and stakeholder involvement. In our quest for knowledge, we came across the enlightening API Design Matters Substack by David Biesack, a renowned expert in the field. We couldn't resist inviting him to our API Intersection podcast to share his invaluable insights on all things design-related.
As the Chief API Officer at Apiture, David focuses on API design and utilizes OpenAPI. Let's look at some of the benefits of OpenAPI for documenting and designing APIs and the importance of consistency in API design.
Catch David's series on the language of api design at apidesignmatters.substack.com and check out his LinkedIn
*disclaimer (31:24): When discussing application/problem+json, the wrong RFC is cited. The correct one is RFC 7807 -- see https://datatracker.ietf.org/doc/html/rfc7807 (Erik Wilde is one of the authors)
_____
To subscribe to the podcast, visit https://stoplight.io/podcast
--- API Intersection Podcast listeners are invited to sign up for Stoplight and save up to $650! Use code INTERSECTION10 to get 10% off a new subscription to Stoplight Platform Starter or Pro.
Offer good for annual or monthly payment option for first-time subscribers. 10% off an annual plan ($650 savings for Pro and $94.80 for Starter) or 10% off your first month ($9.99 for Starter and $39 for Pro).
Mark as Played
Transcript
Episode Transcript
Available transcripts are automatically generated. Complete accuracy is not guaranteed.
(00:00):
Everybodywants their stuff to be successful.
They want their APIs to be used.
They want their user interfacesand programs and applications
to be used, etc..
So that's the primary thing, iscan you solve real problems with it,
and can you get the feedbackfrom those consumers and developers
early enough to tell youyou're on the right path?
(00:21):
I'm Jason Harmonand this is API intersection,
where you'll get insights from experiencedAPI practitioners to learn best
practices on thingslike API design, governance, identity,
versioning and more.
(00:44):
Welcome back to API intersection.
I'm your host Jason Harmon,CTO at Stoplight and
today is one of those days where you know,
I don't get as much timeas I like to go read and learn new stuff.
But every nowand then when I do get the chance,
there's people I trip across thatI just think I want to meet these people.
So our guest today, David Biesack,I hope I said your name right.
(01:06):
I forgot to ask before. All right.
Chief API Officer
-cool title at Apitureis going to join us today
and we'll kind of talk about,you know, talk shop, talk API stuff.
So thanks for coming. David.
Tell us a little bit about yourselfand what you guys do.
Yeah, thanks for inviting me.So I'm Dave Biesack.
I as Jason mentioned, I'mthe chief API officer at Apiture.
(01:27):
I joined the company when it was foundeda little over five years ago
and they set outto become a banking API platform.
So they want to build APIsaround their banking solutions
and brought me on boardto help build the API program there.
So I started out as an API architectand then eventually moved up to where I am
now as chief API officer.
(01:49):
So I'm responsible for the designand architecture of our APIs.
Most of the time I spend in doing thatanalysis and design,
I work with the products
folks who come up with feature requirementand then we map them into APIs.
And then I do API design alongwith another API architect on the team.
His name is Aaron.
So we convert all the basic featurerequirements into APIs
(02:12):
and then the engineering teamsgo in, implement all those APIs,
deploy them and help us secure them, etc..
So most of my work is arounddesigning those APIs,
but all the ancillary thingsthat go along with that as well.
So training other folks on what it meansto be an API first company
and what it means to,you know, tried to design APIs upfront.
(02:35):
And really what we do
is try to gather those requirements and
make them separate fromjust UI requirements or API requirements,
but just be feature requirementsand then build APIs around that.
So I've been doing that ever since.
Very cool.
You're you're are people, you're amongstgood company.
(02:55):
I think there's a lot of folks like,you know,
trying to dothe sort of thing that you're doing
and the thing that I've done before,which I think is very similar,
I think in our audience.
So you're in good company
and you did a heck of a stint at,I guess, S.A.T.s before this, right?
Yeah, I worked at SAS for 28 yearsbefore coming to Aperture,
(03:18):
built a whole career there,
doing all kinds of things.
But I spent my entire timein R&D organization.
When Java came out in 96,I helped SAS adopt the Java platform.
So I was my role there was similar whatI do at Aperture as Chief API officer.
I was the R&D Java strategist,so I helped define Java standards
(03:39):
for the entire organizationand did a lot of training on
Java adoption and building librariesand things like that.
And then the last five years at SAS,I ran the API Center of Excellence,
which was a governing body,so we helped shape
the rest API standards for SAS and worked
as a consulting organization and helpedall the teams design their rest.
(04:02):
APIs according to those standards, worked
on tooling around APIsand things like that.
So it helped with the adoption of of APIsthroughout the R&D organization.
And in those five years,
we we had an API review processand we had about 120 different APIs
that we brought through thatthat design and review process.
(04:23):
While I was there. I
so I guessbringing it back to kind of what
caught my attention as you had startedthis blog post series
that you titled The Language of APIis that I think somewhat hubs around open
API, but I feel likeyou touched on a bunch of other stuff too.
So I mean, kind ofwhat do you feel like is the big point
(04:44):
that you're workingto get across in the series?
Yeah,
so I've always been kind of a languagegeek for my entire professional career,
so I was always interestedin programing languages,
as I mentioned, you know, helpingwith the adoption of Java at SAS, etc.
I was always intriguedby the expressiveness of languages,
how well they can capture your intentas a developer, as a programmer,
(05:08):
how concise versus how verbosethose languages are.
New job is is kind of knownas a relatively verbose language,
but certain language attributescan help improve
that with with type inferenceand things like that.
But basically, how do theyhow do they work as languages
for communicating ideas?
You know, our human language is usedfor expressing ideas and communicating
(05:31):
with each other.
Programing languages are usedfor communicating with the compiler
and the back end and the runtime, butalso for communicating with other people
who are going to be reading those programsand reading that code later.
And so the idea of howwell you can express your ideas
in those languages is really intriguing
(05:52):
to me, and moreso how those languages change over time
and the way we use those languageschanges over time.
And in fact,it comes to be that that oftentimes
those languages influencethe way you think about things.
So the solutions to a programing taskusing
Java are very different from the solutionsyou might come up with.
(06:12):
Using a functional language like Eve Sharpor Scala or even TypeScript and stuff.
So that's what I'm really interestedin, is this notion of languages,
how they capture ideas, howwell you can express your ideas in them,
how they grow,
and how you as a programmer or developergrow along with those languages.
As you acquirethose languages, become more fluent.
(06:34):
You know, it's funny,I think for a kind of fundamentally
technology oriented podcast,I think we probably, if we could ever
figure it out,might have set a record for the number of
professionally trained linguistsand just language geeks.
It's I feel like it's a it'san occupational hazard of when you work
with APIs too much, all of a sudden wordstake on a whole new meaning.
(06:57):
Yeah, I mean, like my favoriteexample is like when someone says
the word metadata, the word means nothing.
It's just an empty, vacuous,full of meaning.
You have to describe what it means
and it usually meansyou didn't think about what to call it.
You get hang ups, right?
So I love this this focus on language.
I think one thing we've heard a lot
(07:18):
from other practitionersis the idea that the words
so you'retalking about kind of programing languages
and that expressiveness, whichis fascinating and we might come back to.
But in terms of describing your platform,when you think about
not just designing one API,but designing a whole portfolio of things
that the words that you use carry greatermeaning
(07:39):
and that a lot of folks, when we ask them,you know, what would you do
if you started from scratch,they said, Find that language.
So I'm curious, like in terms of domaindefinition or capability definition,
whatever you want to call it, you know,how do you approach that sort of thing?
Right.
And this was one of the
the most widely read and shared articlesthat I wrote in this series.
I wrote about,you know, using domain driven design.
(08:02):
And a lot of what we doat Aperture is based off of James
Higginbotham, this book,where he talks about this ADR process and
the title of that article that I wrote
was that API designfirst is not API design first.
You know, everybody hears about APIdesign, API first, there's API first that.
(08:24):
But that's really a misnomeror mischaracterization
because you don't start with the APIno matter what you're doing.
You have to go back
to business requirementsand what problem are you trying to solve?
What problems do your users or
potential users have that can be solved?
You know, hopefully with an APIand really it's understanding that
(08:45):
and using the techniques of domain drivendesign to characterize those problems.
And then an important part of that processis building the ubiquitous language.
You know, what is the set of terms,the vocabulary of your problem domain,
and then making sure everybody understandsand agrees on what those terms mean
(09:06):
so that you're removing ambiguity as youas you move forward.
You go through the rest of the process.
So it's really importantto build that vocabulary
so that everybody understandsthings from the get go.
I mean, it starts with with that,you know, the product requirements
and understanding the domainin which this problem resides
and understanding what those terms are.
(09:28):
And then you have to codify thosein some way.
So they actually become names of,you know, when you do API modeling,
they will filter down and often becomenames of resources in your API model,
or they may become the names ofoperations in your API model.
But, but
that's where I really want people to startis is going back to the source.
What is the problemyou're trying to solve?
(09:49):
And then how do you capture thatwith the language?
And you know, design patterns were reallypopular thing 20, 30 years ago.
And really what's important about designpatterns was this whole notion of
of the pattern language,which is what you use to document
the problems in the forcesand then the patterns that you use
to solve those particular problems.
(10:10):
And I like to see the same mappings
happen with with APIsas they do with just general software
development is you build a languageand you have a way of expressing
either the problem set or the solutionset with with specific languages.
And some languages are good for thatand some languages need need some work.
But, but that's really what intrigues meabout this and understanding what
(10:34):
how languages influence peoplein the way you think.
Yeah, I was.
I think when I've tried to describe thisto people, I'm like,
if, if you had to draw a very naive sort
of graph of the conceptual names of thingsin what you intend to build,
and you just put it on a big marker boardand you walked customers in the room,
(10:54):
would they point and go,Oh yeah, that's my stuff.
You know what they recognize is quickly
conceptually what it isthat they intend to do out of
just the languagewithout anything further diffuse.
And you mentioned kind of DDT is sortof the methodology that you're using.
Are there any sort of specific toolsthat make that process of aligning around
language easier for, you.
(11:16):
Know, specific tools?
You know,
James, in his book, he outlines somesome tools and techniques for doing things
with like spreadsheets and tables of,you know, defining various things.
And we've kind of extended that.
To me, spreadsheets are a little bit
awkward to work with versuswe as a wiki primarily.
So our product team uses various
tools that that product managerslike to use for capturing,
(11:41):
you know, epics and higher level goalsand things like that.
So this is what this productor this feature is going to do.
And then they break it downinto components
and they use various tools for thatand eventually things filter down
from from that method down into thingsthat become, you know, JIRA tickets.
We use JIRA for trackingactivities and our our
(12:04):
sprint cycles and things like that.
So a lot of thingscome down as as JIRA tickets.
But what I do isI have to consolidate all that information
from all these different sources, frominterviews with with the product people.
And we we sit down
and have meetings and we go overand ask questions and things like that.
And then we just basically captureeverything into an API model
that we capturejust on a confluence page as a wiki page.
(12:27):
And it's very easy to collaborate on that.
So we can we can go in hereand we can kind of give a high level view.
What I do isI do this translation exercise.
I take what they give meas product requirements and then
I rephrase itand kind of speak it back to them and say,
Is this the right way of picturing thisor representing this?
Do I have all the elements captured?
(12:50):
Is this a correct representationof what you've told me?
And we iterate on that.
And because when I write things downthis way, then it will of course often
raise a lot of questions.
And so I will write those questions downand then we can iterate on that confidence
page and people can add questionsand write responses in there
and then evolves over time.
It it's pretty easy to to modify
(13:11):
and extend that API modelas we learn more and more.
And the topic that the top of the documentis where I list,
you know, the vocabulary and listwhat are the common terms for this
domain model?
And we make sure people havea kind of understanding of that.
And then that filters down into the lowerlevel
of whatthose API resources are going to be.
And that's tends to workreally, really well
(13:34):
versus something like JIRA, which tends to
fragment your knowledgeand put in lots of different places
that it's oftentimes
really hard to get the bigger pictureof how things interrelate.
You can have an epicthat's got 20 or 30 stories in it
and you have to click on each one,
open a page, read what's in there, readthe acceptance criteria,
(13:54):
and then go back to the next pageand the next page in the next page.
By time you get through the whole thing,you've kind of lost track of where you are
and trying to figure out where did I readthat initial requirement about this
one specific attributeor this one specific behavior?
It gets lost in my mind.
So by consolidating the domain model,the knowledge base
into the conference page really helps me
(14:18):
and is guided by againwith with domain driven design
as these bounded contexts that really kindof fit naturally into your API models.
So you have an API and you focus really on
what is the core element of that API,what is the primary resource
and what are the pieces necessaryto pull that together.
And you cancertainly have related resources
(14:38):
and you can have sub resources, etc.
and you can explain all that.
But usually that that one wiki page talksabout that one specific domain model
and it tried to try to coalesceall the information we need there
in order to then once we narrow that downand we got the basic
API model worked out,then we can transcribe that directly
(14:59):
into an open API document and startbuilding that and that becomes more of,
you know, the design art
of how you capture that into oneor more API documents.
We have a multi document design,so we have a, an API
that's just called common,which is one open
(15:19):
API document that has a bunch of commonreusable components.
So we've got schema components in there,We've got standard
query parameters that might be usedelsewhere, we've got
standard response objectsand things like that.
So those are all part of those components.
And then each individual API,whether it's a, an accounts
API for, for viewing your accountsin your account balances
(15:40):
or it's a transfer's APIfor making transfers or transactions
API that letsyou look at those transaction history
for individual accounts and variousother elements.
You know, we do digital banking, so it'sall kinds of banking related resources.
Each one of those will have its ownAPI model and so an API definition,
an open API, but they can referenceschemas and other things from each other
(16:06):
quite naturally.
And that works really well
with the composition modelthat's supported with open API.
Yeah, for sure.
And I got to double down here and saythat,
you know, we're certainly big fansof James Higginbotham in this process.
And you mentioned ADRand this is a lion defined design refine.
And I think what a lot of whatyou just described is kind of the align
(16:29):
and define part, right?
It's like before you internallyit stopped by you know,
we tend to refer to thisas like the homework that happens
before you design.
And it's like a lot of it is just markerboards and spreadsheets and mirror charts.
And it's kind of a loosely defined thing
that you can't point to and say, Well,go use that tool and we'll do it.
(16:53):
It's about the discussion
and about the alignmentand having a user definition of it.
Yeah, it's very much communicationis just so, so central and key to that.
And the notion of collaborationis really, really critical there.
Yeah,
because it's,
you know, when I worked at SAS SAS, it was
(17:14):
and is hugely based on analytics, right?
That's their breadand butter is analytics.
But I never really learnedor became an analytics expert.
I didn't really know the domain modelvery well.
I just I just kind of knew APIs
and interfacesand kind of software design.
But all the work that I did as askedreally wasn't analytics based.
(17:37):
There were a lot of otherpeople were way smarter in that.
And PhDs in analytics.
ET cetera, you know who did all that work?
And then at Aperture,
I came into the companywithout any banking experience at all.
So I relied very heavilyon the domain experts
to teach me the domain ideas, you know.
And so I learned quite a bitabout banking,
(17:59):
but I'm not a bankerand I'm not a financial person.
I'm an API person.
But it's importantfor us to be able to communicate and work
because,you know, these banking domain people,
they don't really know APIs,They don't know what's
what's possible with APIsor they don't know good ways to structure
and manage an API program for evolutionand things like that.
(18:20):
And so it has to be teamwork there.
And we kind of teach each other as we goalong.
Yeah, I think it's one of the funnieraspects of working on kind of,
you know, platform engineeringAPIs kind of topics is
you find yourself in all kinds of things.
And these days it's like,
look around the room, there's API,it's getting called right now, right?
(18:40):
It's everywhere.
It's in everything.
You know, your fridgeand your washer are talking.
This stuff.
You know, we're reminded of thisa lot at a stoplight where it's like,
you know,our top customers make like beer,
electrical parts,shipping, automation, stuff.
Like very,you know, traditional business lines.
And you go, Well, yeah, like at its core,integration was always about supply
(19:04):
chain automation, right?
So it's really interesting that,
you know, I did a stint in fintech
and that sort of stuff and I came awaywith a better understanding of it.
But if someone said, you know, describe
how the payment stack of the worldworks, I'd be like,
I'll tell you to talk to you.
But, you know,
I trusted them in the definitionand just created the right guardrails
(19:25):
so that it looked and smelledand felt like the other things.
And so I'm with you on that.
I think back to our sort
of language of APIs arc here.
You know,we touched on programing languages
and some of that expressivenessand kind of how to define these domains.
But I guess you mentioned in the course of
(19:46):
that open API is sort of the waythat you're expressing those things
and sort ofkicking off the development process.
So how do you see that sort of fitting in?
So we adopted Open
API at Aperture when I came in, you know,I kind of said
this is probably the best representationof how to capture an API design.
(20:07):
There were lots of other competingstandards at the time.
You know, there's Ramle and there's APIblueprints and all kinds of other things.
But but Open APIkind of had the momentum going in
an open API 3.0 had been outand the tooling around
that specificationwas really kind of the kicker.
You know, by having awell defined and constrained language
(20:32):
for expressing an API designreally enables the tools and stuff.
So I have lots of issues with open APIthat I would like to change if I could.
But you know, there's lots of waysthat I would really like to extend open
API and it goes back toI think if you go back to like issue like
182 and the GitHub repo is one an idea
(20:54):
that I put in there many, many years agothat hasn't been adopted yet.
But there's a lot of peoplewho seem to like
that idea of just extending ita little bit in a different direction.
But it's interestingbecause it has constraints and
constraints are really kind of important.
You know, if open API adoptedeverybody's wish
(21:14):
and made all these changes,it would become untenable.
It would become unusable.
So those constraints are reallywhat are interesting.
And it was actually one of the
it was my last postthat I got and published on my my blog
and the Substackwas about growing a language.
And this is the 25th anniversary of GuySteel's seminal talk of the same name
(21:38):
I was recording. That was at the
OOP slot,
who was object oriented
programing systems, languagesand Applications and ACM conference
that was held every yearand they bring him to splash since then.
But 25 years ago he gave this really greattalk about growing a language.
And he was he was on staff at SunMicrosystems at the time.
(21:58):
Java was was growing in popularity.
And there were all these requeststo extend job at this direction
or extend Java in that directionto add this new feature here.
And he talked about, you know, how you goabout growing a language like Java
in this appliesdirectly to growing a language
like the open API specificationor growing a language like JSON schemas.
(22:19):
He talked about the forcesthat come to play
and how you have to weigh all those forcesand think about the long term evolution
and what's going to be sustainableand things.
So it's it's a fabulous talk.
If people have not watched it,it's really it's really good to to to see.
I think anybody who doesany kind of software design,
especially around languages,should really be familiar with that.
(22:41):
So so we adopted open API
and you know, haven't regretted that inany by any means
because of the expressiveness that it has,even though it's constrained.
Sometimes those constraintsare really helpful to help you focus
on what it is you're really trying to say
and with it with constrained language,
(23:04):
you can still have quitea bit of expressiveness
and it's kind of nicebecause it leads itself
to a much more consistent viewof what your APIs will look like
because you can't express completely wildand crazy different things.
So anybody who's looking at an open APIdefinition understands its structure
(23:24):
and they understand the meaningof all the constructs in that document
and and things.
So it helpswith, with the understanding of the API.
So that's what's really beneficialabout it.
In addition to itbeing, you know, adjacent document
that can be passedand processed and analyzed, you can use it
for co-generation,you can use it for for creating marks,
(23:45):
you can use it for creating your,
your documentationand you can use it for creating stickers
and all manner of deploymentmethods and everything else.
So it's really beneficial thereand it's proven to be pretty powerful
and expressivegiven that constraint that it has.
Yeah, I mean, to some extentwhat you're really describing
(24:06):
is the design by constraints methodologyapplied to HTP in general, right?
Like Fielding was trying
to sort of express the possibilitieswith HTP programmatically.
So I think it even goes beyond that.
I have to comment to on like themaintaining open API and how hard it is.
I was actually part of the founding crewon the Open API initiative
and alongside Ron Rutkowski was supposedto be the referee for the group.
(24:29):
And yeah, when you see all of the world'sperspectives
on how to design an APIand have to make choices, it's hard.
It's really hardand my favorite example is
stuff like Discriminator and Open APIand like the fact
that it's never really quiteworked right in any tooling.
For my money, it's likeit's probably should've never been there.
(24:50):
The yes, people want to do that,but it's like every time I've worked
with folks on Why are you tryingto build a polymer morphic API?
Write something that changes its meaningdepending on what you're doing.
Usually there's a cleaner way to do it,
and I think even to connect backto your earlier point that like
there's so many languagesthat express different things,
(25:11):
the API designer'sjob is often to think about how to get rid
of all that flavor and come backto really just the foundations of object
oriented principles, thingsthat are applicable in every language.
And it's a really tough set of constraintsto work with,
but it's kind of what makes it all work.
So yeah, right. Tricky for sure.
Yeah.
So, you know,we're, we're taking into account
(25:34):
all these, you know, sort of open APIand expressing things and all that.
And, you know, I know one of the struggleshistorically has always been,
you know, you write down a bunch of rulesand standard and then you ask,
you know, all the developers in a companyand really large ones, it's
hard to even communicatethat, that, hey, do it this way right?
(25:56):
And to to
sort of produce this feelingthat a bunch of APIs
feel like one thing,They feel like one platform.
So but that's hard, right?
So like, what's your approach to sort ofbuilding that consistency of design?
Well, you mentioned guardrails earlier,and I think that's
that's an important aspect.
So when I worked at SAS,it was a very large organization.
(26:18):
So it was it was very hard to
have people kind ofhave the same mindsets,
which is really kind of what's necessary
if you want to havea consistent set of APIs,
you know, and we had marginal successthere, you know,
so, you know,we had kind of API design standards.
We said, you know,you should do it this way.
You should avoid this particular practice.
(26:38):
This is how you should name thingsand things like that, you know,
which only goes so faruntil you can really
you can't codify a mindsetin an API style guide,
but youcan certainly try to communicate again.
And really the best way to dothat is two examples.
Now at Aperture, it was it was muchsimpler job because I was for a long time,
(26:59):
for four years
I was the only API architect,I was the only person designing the APIs.
So I, you know,I was able to just kind of use
the same style throughoutand had that consistent voice.
It's good to be the king, right?
I'm sorry.
It's good to be the king.Yeah, yeah, yeah.
But but even even over time,you know, that that voice changes.
And I can see where
(27:20):
there arethings that I designed for years ago
that were designedcompletely differently today.
And that's a really hard thingto, to really manage,
especially for a larger organization.
So but the best way to gois, is try to, to, you know,
keep in mind,you know, who you writing these APIs for,
they're they're written to be usedand written to be consumed.
(27:42):
They're not writtento be put up on a pedestal and say,
look how beautifulthis API is, isn't it elegant looking?
Right.
The real judge of that is can developerssolve problems with the API?
Can they actually consumeit and use it? Can they
adopt it quickly?
Do they know how to use it?
Can they infer how to use itbecause it's consistent, for example?
(28:05):
So if you do something in one place,the way you do pagination, one
part of the API should be the sameas what you do in another part of the API.
So selling people on that and really wantstheir software to be used.
So in order to get people to kind of buyinto any kind of governance product
or a program or anything like that, it's
the same thingas with user interfaces, right?
(28:25):
If it's inconsistent,
it's going to be harder for people to use.
It's not going to be as successful.
Somebody wants their stuffto be successful.
They want their APIs to be used.
They want to use interfaces and programsand applications to be used, etc..
So that's the primary thing, iscan you solve real problems with it
and can you get the feedbackfrom those consumers and developers
(28:48):
early enough to tell youyou're on the right path?
Or at least later on you get the feedbackthat yes, I am using it
and it is successful and then you use thatas a showcase for other people.
So when you have new peoplecoming into the company,
you can point them to your historyand say, You know, this style of API
works really well.
This one that we put out theretwo years ago, no one's really using it.
(29:11):
You know, maybe it'sdesign is isn't really kind of
doesn'treally meet the need and things like that.
So there's a lot of good informationcoming about now around governance.
So I know I know Laura over at Postmanis doing a lot of stuff
writing about governanceand he takes a, you know, kind of a
I don't want to say it'sa non-intrusive approach to governance.
(29:34):
It's really you have some guardrails,but you're really trying to lead
rather than push,you know, lead by example,
rather than forcing peopleto go down a specific path.
But basically, if everybody is on boardwith with the goals of the organization
and why you're doing this work to beginwith, then then that's really
what you used to incent people to,to come up with good consistent APIs.
(29:59):
Yeah.
And you had mentioned and written
about kind of,you know, thinking in dry terms, right?
Don't repeat yourself.
And I think that's a big partof what you're describing here.
And I like to express it that
your code base being
dry is far less importantthan the community of consumption
(30:20):
around that APIand how drive that code is set.
To your point on, can you canyou have common consistent patterns
that are used across
the whole portfolio of APIs means thatthe clients are using more than one API.
Just write up a bunch of their code and
you know, working at like pay per hour.
We have like a million developernetwork, right?
I'm like, you add one line of code to thatand you just added
(30:44):
10,000 lines of code next monthfor all the clients writing against us.
So if it's harder for you, fine.
Like that's the way I think for the broadaudience, because at the end of the day,
their time is more valuable than oursin terms of growing the business.
So that's that's an important that's animportant point because I have to kind of
sometimes clarify it to the engineerswho are building the APIs.
(31:07):
You know, they asked me,why do you make my job so hard?
And same because we're tryingto make the developers job easier,
you know, making the APIs easy to use
pays over multiple times in the effortthat we put forth initially.
You know, and a good example of that is sowe adopted
our see was a 4707
the problem plus JSON application problemplus JSON standard
(31:31):
for, you know, a standard error responseor they call it a problem response
because it doesn't have to be an error,could just be a problem.
And we adopted that pretty early
in our in our current cycle
of of new APIsthat we're doing for our platform.
And you know, we,we use it, but we extended it
so you know you have these
(31:52):
types deal on the air, which is a URLthat describes what that type means.
And so we have lots of different waysof expressing lots of different type
types of errors. So when you have a 422
that says unprocessed entity,right, syntactically valid.
But but there's something inside of itthat I can't deal with.
It's,it's internally inconsistent or whatever,
you know,So we have lots of different error types
(32:14):
that can be associated with a 422And sometimes people think
it's really kind of hard to manage
all those in the code base and generateswrite errors and things like that.
But, but it yieldsso many benefits to the developer who,
if you just returned back 422without explaining why
they're just lost right inor if it's a 400, why is it a 400?
(32:35):
We'll give them some hints.
And what we even do is we go beyond justdescribing what the areas with the detail.
We also have like a remediation thing.
How do you actually fixthis particular error?
So with every error type that we have,
we also have remediation that sayswhat you can do to to rectify it.
And that's there for the developersto make the developers job easier
so they get back reasonable errorsfrom the system
(32:58):
rather than just generic things that don'ttell them any information at all.
And the other part of this is,as you said, consistency.
So since open API is a standard document
format, we also have a whole bunchof templates that we use
and we have a tool to generate openAPI definitions from from these templates.
So you can really bootstrap an entire API
(33:20):
by just adding a couple annotations
to say, okay, I've got a,
I've got a resource here and I want togenerate some basic crystal operations
or I've got another resource over here andI want to add some actions to modify it.
Or here's a singletonobject over here, doesn't
have all the crystal operations around it,but it but it's managed this way.
And so we have a
(33:40):
we have, you know, five or sixdifferent patterns that we can express
with a simple annotation.
And then and you just code that brieflyand push a button and it generates
all the kind of standard boilerplatearound all those operations
and it puts in the security requirementsfor each of the operations
and it puts the tags in there and it givesyou response and requester response
(34:04):
schema placeholders, and it just generatesall this boilerplate for you
and then lets you work onwhat's important, right?
Because all that boilerplate, all thatstandard stuff, that's always the same.
You shouldn't have to deal with.You shouldn't have to write that.
You shouldn'teven have to copy and paste it.
But something else, do it.
And that's what this tool does,
and that gives you a standard layoutfor all of your APIs.
(34:24):
And then you just have to kind of fillin what's different,
adding new query parameters
to this operation or define youryour schemas over here, etc..
And then you can concentrate on the moreinteresting parts of writing an API,
which is really kind of what you're doingand what what the messages look like.
All right, I'm going to have to talk youinto give me a demo of this thing.
Letter. It sounds cool.
(34:46):
Shout out to Eric Velda, a
wild for for the Anglicized pronunciation
friend of the showwho helped develop that.
The problem detailsfor each of the papers.
And I totally second that advicelike don't make up error models. It's
so hard to do from scratch and I reallyfeel like this solved the problem.
(35:07):
And it's like the number one thingpeople screw up when they first build
an API is don't think better. It's so.
Wonderful.
Yeah, it's it's, it's a standard like memethat we see on all these different forms
APIs is return of 200 error equals true.
To totally don't break the basic rulesthat.
(35:27):
HTP API.
Yeah cool.
So I guess as you knowwe're kind of hit in time here.
I'm sure we're losing listenerswith boredom and other things to do
and any other sort of parting wordsof for us here.
And I'm always empathetic to folks
listening who are like overwhelmedby all the things you just said to do.
(35:50):
Where would they get started? Yeah.
So we're really fortunate in thatthe API community
is so open and accepting.
So there's lots of different placesthat you can jump in.
There's a lot of different Slack instancesout there.
APIs you won't hate is a good one.
There's Discord servers and stuffand then there are conferences.
(36:13):
So API days is going next week.
I'm not going to thatbut but Aaron, our API architect is
but there's API specification conferenceusually in the fall every year
hopefully they'll they'll do that againthis year.
I haven't heard anything about that butget involved with the community in one way
or another and follow what's going onwith the open API specification session
(36:34):
and project moonwalk,which is, you know, the next version,
the next rev of that specification, jumpin and make your voice heard.
The more
perspectives that we have, the better offthe environment is going to be.
But there's so many peoplethat you can call on and,
and if you don't have someoneat your own company that can be a mentor,
(36:54):
you know,
look outside your company and reach outin those other communities and say,
hey, I'm kind of new at this.
I know there's a lot to learn.
Is there anybody who could kind of help me
walk through my journey with meand help me grow
and understand, you know,the good ways of building an API program,
the good ways of designing an API,the good ways of of gathering requirements
(37:18):
and sharing that align and define facewith my product team.
You know, how do I succeedwith all these elements of API design?
There's a lot of people out there
reach outand as I said, they're very welcoming and.
People really dowant to help each other out.
So join the community.
Don't don't be afraid of jumping in
(37:39):
and you'll probably reap lots of benefits.
Of that advice. It's instead true.
I think it's part of what suck me intothe API vortex is just,
you know, I don't know.
People speak my language,you know, and people who somehow
if if they stay in it, have thisinnate will to try to describe the world.
(38:00):
Right?
This is what we've been talking aboutis now
that APIs are everywhere,we have to describe the world.
So how do we do it?
How are we going to put our headstogether?
Charlottesville surgeon for his API,As you will hate
former stop writer and regular contributorLevy you feel
well, David, thanks so much for being on.
Tell folks where they can find outabout all your writing stuff.
You're kind of mentioned in there,but where do they go?
(38:20):
Find it online.
Yeah, so it's on APIdesign matters, dot substack dot com.
It's all one word.
So the general the general Substackis called API design matters.
So it's all mattersrelated to APIs large and small.
And right now this,
the series that I'm doingis the, the language of API design,
but that's just a short seriesthat'll conclude.
(38:41):
But the broader one, it's just API design
matters.
Not well, thanks for sharing everythingwith the community
and we'll all follow along.
Except for Schade.
It's been a pleasure talking with you.
Thanks for listening.
If you have a question you want to ask,look in the description of whichever
(39:01):
platform you're viewing or listening onand there should be a link there
so you can go submit a questionand we'll do our best to find out
the right answer for you.
API Intersection Podcast listeners
are invited to sign up for Stoplightand save up to $650.
Use the code intersectionten to get 10% off a new subscription
(39:22):
to Stoplight Platform starter or pro.
Take a look at this episode'sdescription for more details.
Everybodywants their stuff to be successful.
They want their APIs to be used.
They want their user interfacesand programs and applications
to be used, etc..
So that's the primary thing, iscan you solve real problems with it,
and can you get the feedbackfrom those consumers and developers
early enough to tell youyou're on the right path?
(00:21):
I'm Jason Harmonand this is API intersection,
where you'll get insights from experiencedAPI practitioners to learn best
practices on thingslike API design, governance, identity,
versioning and more.
(00:44):
Welcome back to API intersection.
I'm your host Jason Harmon,CTO at Stoplight and
today is one of those days where you know,
I don't get as much timeas I like to go read and learn new stuff.
But every nowand then when I do get the chance,
there's people I trip across thatI just think I want to meet these people.
So our guest today, David Biesack,I hope I said your name right.
(01:06):
I forgot to ask before. All right.
Chief API Officer
-cool title at Apitureis going to join us today
and we'll kind of talk about,you know, talk shop, talk API stuff.
So thanks for coming. David.
Tell us a little bit about yourselfand what you guys do.
Yeah, thanks for inviting me.So I'm Dave Biesack.
I as Jason mentioned, I'mthe chief API officer at Apiture.
(01:27):
I joined the company when it was foundeda little over five years ago
and they set outto become a banking API platform.
So they want to build APIsaround their banking solutions
and brought me on boardto help build the API program there.
So I started out as an API architectand then eventually moved up to where I am
now as chief API officer.
(01:49):
So I'm responsible for the designand architecture of our APIs.
Most of the time I spend in doing thatanalysis and design,
I work with the products
folks who come up with feature requirementand then we map them into APIs.
And then I do API design alongwith another API architect on the team.
His name is Aaron.
So we convert all the basic featurerequirements into APIs
(02:12):
and then the engineering teamsgo in, implement all those APIs,
deploy them and help us secure them, etc..
So most of my work is arounddesigning those APIs,
but all the ancillary thingsthat go along with that as well.
So training other folks on what it meansto be an API first company
and what it means to,you know, tried to design APIs upfront.
(02:35):
And really what we do
is try to gather those requirements and
make them separate fromjust UI requirements or API requirements,
but just be feature requirementsand then build APIs around that.
So I've been doing that ever since.
Very cool.
You're you're are people, you're amongstgood company.
(02:55):
I think there's a lot of folks like,you know,
trying to dothe sort of thing that you're doing
and the thing that I've done before,which I think is very similar,
I think in our audience.
So you're in good company
and you did a heck of a stint at,I guess, S.A.T.s before this, right?
Yeah, I worked at SAS for 28 yearsbefore coming to Aperture,
(03:18):
built a whole career there,
doing all kinds of things.
But I spent my entire timein R&D organization.
When Java came out in 96,I helped SAS adopt the Java platform.
So I was my role there was similar whatI do at Aperture as Chief API officer.
I was the R&D Java strategist,so I helped define Java standards
(03:39):
for the entire organizationand did a lot of training on
Java adoption and building librariesand things like that.
And then the last five years at SAS,I ran the API Center of Excellence,
which was a governing body,so we helped shape
the rest API standards for SAS and worked
as a consulting organization and helpedall the teams design their rest.
(04:02):
APIs according to those standards, worked
on tooling around APIsand things like that.
So it helped with the adoption of of APIsthroughout the R&D organization.
And in those five years,
we we had an API review processand we had about 120 different APIs
that we brought through thatthat design and review process.
(04:23):
While I was there. I
so I guessbringing it back to kind of what
caught my attention as you had startedthis blog post series
that you titled The Language of APIis that I think somewhat hubs around open
API, but I feel likeyou touched on a bunch of other stuff too.
So I mean, kind ofwhat do you feel like is the big point
(04:44):
that you're workingto get across in the series?
Yeah,
so I've always been kind of a languagegeek for my entire professional career,
so I was always interestedin programing languages,
as I mentioned, you know, helpingwith the adoption of Java at SAS, etc.
I was always intriguedby the expressiveness of languages,
how well they can capture your intentas a developer, as a programmer,
(05:08):
how concise versus how verbosethose languages are.
New job is is kind of knownas a relatively verbose language,
but certain language attributescan help improve
that with with type inferenceand things like that.
But basically, how do theyhow do they work as languages
for communicating ideas?
You know, our human language is usedfor expressing ideas and communicating
(05:31):
with each other.
Programing languages are usedfor communicating with the compiler
and the back end and the runtime, butalso for communicating with other people
who are going to be reading those programsand reading that code later.
And so the idea of howwell you can express your ideas
in those languages is really intriguing
(05:52):
to me, and moreso how those languages change over time
and the way we use those languageschanges over time.
And in fact,it comes to be that that oftentimes
those languages influencethe way you think about things.
So the solutions to a programing taskusing
Java are very different from the solutionsyou might come up with.
(06:12):
Using a functional language like Eve Sharpor Scala or even TypeScript and stuff.
So that's what I'm really interestedin, is this notion of languages,
how they capture ideas, howwell you can express your ideas in them,
how they grow,
and how you as a programmer or developergrow along with those languages.
As you acquirethose languages, become more fluent.
(06:34):
You know, it's funny,I think for a kind of fundamentally
technology oriented podcast,I think we probably, if we could ever
figure it out,might have set a record for the number of
professionally trained linguistsand just language geeks.
It's I feel like it's a it'san occupational hazard of when you work
with APIs too much, all of a sudden wordstake on a whole new meaning.
(06:57):
Yeah, I mean, like my favoriteexample is like when someone says
the word metadata, the word means nothing.
It's just an empty, vacuous,full of meaning.
You have to describe what it means
and it usually meansyou didn't think about what to call it.
You get hang ups, right?
So I love this this focus on language.
I think one thing we've heard a lot
(07:18):
from other practitionersis the idea that the words
so you'retalking about kind of programing languages
and that expressiveness, whichis fascinating and we might come back to.
But in terms of describing your platform,when you think about
not just designing one API,but designing a whole portfolio of things
that the words that you use carry greatermeaning
(07:39):
and that a lot of folks, when we ask them,you know, what would you do
if you started from scratch,they said, Find that language.
So I'm curious, like in terms of domaindefinition or capability definition,
whatever you want to call it, you know,how do you approach that sort of thing?
Right.
And this was one of the
the most widely read and shared articlesthat I wrote in this series.
I wrote about,you know, using domain driven design.
(08:02):
And a lot of what we doat Aperture is based off of James
Higginbotham, this book,where he talks about this ADR process and
the title of that article that I wrote
was that API designfirst is not API design first.
You know, everybody hears about APIdesign, API first, there's API first that.
(08:24):
But that's really a misnomeror mischaracterization
because you don't start with the APIno matter what you're doing.
You have to go back
to business requirementsand what problem are you trying to solve?
What problems do your users or
potential users have that can be solved?
You know, hopefully with an APIand really it's understanding that
(08:45):
and using the techniques of domain drivendesign to characterize those problems.
And then an important part of that processis building the ubiquitous language.
You know, what is the set of terms,the vocabulary of your problem domain,
and then making sure everybody understandsand agrees on what those terms mean
(09:06):
so that you're removing ambiguity as youas you move forward.
You go through the rest of the process.
So it's really importantto build that vocabulary
so that everybody understandsthings from the get go.
I mean, it starts with with that,you know, the product requirements
and understanding the domainin which this problem resides
and understanding what those terms are.
(09:28):
And then you have to codify thosein some way.
So they actually become names of,you know, when you do API modeling,
they will filter down and often becomenames of resources in your API model,
or they may become the names ofoperations in your API model.
But, but
that's where I really want people to startis is going back to the source.
What is the problemyou're trying to solve?
(09:49):
And then how do you capture thatwith the language?
And you know, design patterns were reallypopular thing 20, 30 years ago.
And really what's important about designpatterns was this whole notion of
of the pattern language,which is what you use to document
the problems in the forcesand then the patterns that you use
to solve those particular problems.
(10:10):
And I like to see the same mappings
happen with with APIsas they do with just general software
development is you build a languageand you have a way of expressing
either the problem set or the solutionset with with specific languages.
And some languages are good for thatand some languages need need some work.
But, but that's really what intrigues meabout this and understanding what
(10:34):
how languages influence peoplein the way you think.
Yeah, I was.
I think when I've tried to describe thisto people, I'm like,
if, if you had to draw a very naive sort
of graph of the conceptual names of thingsin what you intend to build,
and you just put it on a big marker boardand you walked customers in the room,
(10:54):
would they point and go,Oh yeah, that's my stuff.
You know what they recognize is quickly
conceptually what it isthat they intend to do out of
just the languagewithout anything further diffuse.
And you mentioned kind of DDT is sortof the methodology that you're using.
Are there any sort of specific toolsthat make that process of aligning around
language easier for, you.
(11:16):
Know, specific tools?
You know,
James, in his book, he outlines somesome tools and techniques for doing things
with like spreadsheets and tables of,you know, defining various things.
And we've kind of extended that.
To me, spreadsheets are a little bit
awkward to work with versuswe as a wiki primarily.
So our product team uses various
tools that that product managerslike to use for capturing,
(11:41):
you know, epics and higher level goalsand things like that.
So this is what this productor this feature is going to do.
And then they break it downinto components
and they use various tools for thatand eventually things filter down
from from that method down into thingsthat become, you know, JIRA tickets.
We use JIRA for trackingactivities and our our
(12:04):
sprint cycles and things like that.
So a lot of thingscome down as as JIRA tickets.
But what I do isI have to consolidate all that information
from all these different sources, frominterviews with with the product people.
And we we sit down
and have meetings and we go overand ask questions and things like that.
And then we just basically captureeverything into an API model
that we capturejust on a confluence page as a wiki page.
(12:27):
And it's very easy to collaborate on that.
So we can we can go in hereand we can kind of give a high level view.
What I do isI do this translation exercise.
I take what they give meas product requirements and then
I rephrase itand kind of speak it back to them and say,
Is this the right way of picturing thisor representing this?
Do I have all the elements captured?
(12:50):
Is this a correct representationof what you've told me?
And we iterate on that.
And because when I write things downthis way, then it will of course often
raise a lot of questions.
And so I will write those questions downand then we can iterate on that confidence
page and people can add questionsand write responses in there
and then evolves over time.
It it's pretty easy to to modify
(13:11):
and extend that API modelas we learn more and more.
And the topic that the top of the documentis where I list,
you know, the vocabulary and listwhat are the common terms for this
domain model?
And we make sure people havea kind of understanding of that.
And then that filters down into the lowerlevel
of whatthose API resources are going to be.
And that's tends to workreally, really well
(13:34):
versus something like JIRA, which tends to
fragment your knowledgeand put in lots of different places
that it's oftentimes
really hard to get the bigger pictureof how things interrelate.
You can have an epicthat's got 20 or 30 stories in it
and you have to click on each one,
open a page, read what's in there, readthe acceptance criteria,
(13:54):
and then go back to the next pageand the next page in the next page.
By time you get through the whole thing,you've kind of lost track of where you are
and trying to figure out where did I readthat initial requirement about this
one specific attributeor this one specific behavior?
It gets lost in my mind.
So by consolidating the domain model,the knowledge base
into the conference page really helps me
(14:18):
and is guided by againwith with domain driven design
as these bounded contexts that really kindof fit naturally into your API models.
So you have an API and you focus really on
what is the core element of that API,what is the primary resource
and what are the pieces necessaryto pull that together.
And you cancertainly have related resources
(14:38):
and you can have sub resources, etc.
and you can explain all that.
But usually that that one wiki page talksabout that one specific domain model
and it tried to try to coalesceall the information we need there
in order to then once we narrow that downand we got the basic
API model worked out,then we can transcribe that directly
(14:59):
into an open API document and startbuilding that and that becomes more of,
you know, the design art
of how you capture that into oneor more API documents.
We have a multi document design,so we have a, an API
that's just called common,which is one open
(15:19):
API document that has a bunch of commonreusable components.
So we've got schema components in there,We've got standard
query parameters that might be usedelsewhere, we've got
standard response objectsand things like that.
So those are all part of those components.
And then each individual API,whether it's a, an accounts
API for, for viewing your accountsin your account balances
(15:40):
or it's a transfer's APIfor making transfers or transactions
API that letsyou look at those transaction history
for individual accounts and variousother elements.
You know, we do digital banking, so it'sall kinds of banking related resources.
Each one of those will have its ownAPI model and so an API definition,
an open API, but they can referenceschemas and other things from each other
(16:06):
quite naturally.
And that works really well
with the composition modelthat's supported with open API.
Yeah, for sure.
And I got to double down here and saythat,
you know, we're certainly big fansof James Higginbotham in this process.
And you mentioned ADRand this is a lion defined design refine.
And I think what a lot of whatyou just described is kind of the align
(16:29):
and define part, right?
It's like before you internallyit stopped by you know,
we tend to refer to thisas like the homework that happens
before you design.
And it's like a lot of it is just markerboards and spreadsheets and mirror charts.
And it's kind of a loosely defined thing
that you can't point to and say, Well,go use that tool and we'll do it.
(16:53):
It's about the discussion
and about the alignmentand having a user definition of it.
Yeah, it's very much communicationis just so, so central and key to that.
And the notion of collaborationis really, really critical there.
Yeah,
because it's,
you know, when I worked at SAS SAS, it was
(17:14):
and is hugely based on analytics, right?
That's their breadand butter is analytics.
But I never really learnedor became an analytics expert.
I didn't really know the domain modelvery well.
I just I just kind of knew APIs
and interfacesand kind of software design.
But all the work that I did as askedreally wasn't analytics based.
(17:37):
There were a lot of otherpeople were way smarter in that.
And PhDs in analytics.
ET cetera, you know who did all that work?
And then at Aperture,
I came into the companywithout any banking experience at all.
So I relied very heavilyon the domain experts
to teach me the domain ideas, you know.
And so I learned quite a bitabout banking,
(17:59):
but I'm not a bankerand I'm not a financial person.
I'm an API person.
But it's importantfor us to be able to communicate and work
because,you know, these banking domain people,
they don't really know APIs,They don't know what's
what's possible with APIsor they don't know good ways to structure
and manage an API program for evolutionand things like that.
(18:20):
And so it has to be teamwork there.
And we kind of teach each other as we goalong.
Yeah, I think it's one of the funnieraspects of working on kind of,
you know, platform engineeringAPIs kind of topics is
you find yourself in all kinds of things.
And these days it's like,
look around the room, there's API,it's getting called right now, right?
(18:40):
It's everywhere.
It's in everything.
You know, your fridgeand your washer are talking.
This stuff.
You know, we're reminded of thisa lot at a stoplight where it's like,
you know,our top customers make like beer,
electrical parts,shipping, automation, stuff.
Like very,you know, traditional business lines.
And you go, Well, yeah, like at its core,integration was always about supply
(19:04):
chain automation, right?
So it's really interesting that,
you know, I did a stint in fintech
and that sort of stuff and I came awaywith a better understanding of it.
But if someone said, you know, describe
how the payment stack of the worldworks, I'd be like,
I'll tell you to talk to you.
But, you know,
I trusted them in the definitionand just created the right guardrails
(19:25):
so that it looked and smelledand felt like the other things.
And so I'm with you on that.
I think back to our sort
of language of APIs arc here.
You know,we touched on programing languages
and some of that expressivenessand kind of how to define these domains.
But I guess you mentioned in the course of
(19:46):
that open API is sort of the waythat you're expressing those things
and sort ofkicking off the development process.
So how do you see that sort of fitting in?
So we adopted Open
API at Aperture when I came in, you know,I kind of said
this is probably the best representationof how to capture an API design.
(20:07):
There were lots of other competingstandards at the time.
You know, there's Ramle and there's APIblueprints and all kinds of other things.
But but Open APIkind of had the momentum going in
an open API 3.0 had been outand the tooling around
that specificationwas really kind of the kicker.
You know, by having awell defined and constrained language
(20:32):
for expressing an API designreally enables the tools and stuff.
So I have lots of issues with open APIthat I would like to change if I could.
But you know, there's lots of waysthat I would really like to extend open
API and it goes back toI think if you go back to like issue like
182 and the GitHub repo is one an idea
(20:54):
that I put in there many, many years agothat hasn't been adopted yet.
But there's a lot of peoplewho seem to like
that idea of just extending ita little bit in a different direction.
But it's interestingbecause it has constraints and
constraints are really kind of important.
You know, if open API adoptedeverybody's wish
(21:14):
and made all these changes,it would become untenable.
It would become unusable.
So those constraints are reallywhat are interesting.
And it was actually one of the
it was my last postthat I got and published on my my blog
and the Substackwas about growing a language.
And this is the 25th anniversary of GuySteel's seminal talk of the same name
(21:38):
I was recording. That was at the
OOP slot,
who was object oriented
programing systems, languagesand Applications and ACM conference
that was held every yearand they bring him to splash since then.
But 25 years ago he gave this really greattalk about growing a language.
And he was he was on staff at SunMicrosystems at the time.
(21:58):
Java was was growing in popularity.
And there were all these requeststo extend job at this direction
or extend Java in that directionto add this new feature here.
And he talked about, you know, how you goabout growing a language like Java
in this appliesdirectly to growing a language
like the open API specificationor growing a language like JSON schemas.
(22:19):
He talked about the forcesthat come to play
and how you have to weigh all those forcesand think about the long term evolution
and what's going to be sustainableand things.
So it's it's a fabulous talk.
If people have not watched it,it's really it's really good to to to see.
I think anybody who doesany kind of software design,
especially around languages,should really be familiar with that.
(22:41):
So so we adopted open API
and you know, haven't regretted that inany by any means
because of the expressiveness that it has,even though it's constrained.
Sometimes those constraintsare really helpful to help you focus
on what it is you're really trying to say
and with it with constrained language,
(23:04):
you can still have quitea bit of expressiveness
and it's kind of nicebecause it leads itself
to a much more consistent viewof what your APIs will look like
because you can't express completely wildand crazy different things.
So anybody who's looking at an open APIdefinition understands its structure
(23:24):
and they understand the meaningof all the constructs in that document
and and things.
So it helpswith, with the understanding of the API.
So that's what's really beneficialabout it.
In addition to itbeing, you know, adjacent document
that can be passedand processed and analyzed, you can use it
for co-generation,you can use it for for creating marks,
(23:45):
you can use it for creating your,
your documentationand you can use it for creating stickers
and all manner of deploymentmethods and everything else.
So it's really beneficial thereand it's proven to be pretty powerful
and expressivegiven that constraint that it has.
Yeah, I mean, to some extentwhat you're really describing
(24:06):
is the design by constraints methodologyapplied to HTP in general, right?
Like Fielding was trying
to sort of express the possibilitieswith HTP programmatically.
So I think it even goes beyond that.
I have to comment to on like themaintaining open API and how hard it is.
I was actually part of the founding crewon the Open API initiative
and alongside Ron Rutkowski was supposedto be the referee for the group.
(24:29):
And yeah, when you see all of the world'sperspectives
on how to design an APIand have to make choices, it's hard.
It's really hardand my favorite example is
stuff like Discriminator and Open APIand like the fact
that it's never really quiteworked right in any tooling.
For my money, it's likeit's probably should've never been there.
(24:50):
The yes, people want to do that,but it's like every time I've worked
with folks on Why are you tryingto build a polymer morphic API?
Write something that changes its meaningdepending on what you're doing.
Usually there's a cleaner way to do it,
and I think even to connect backto your earlier point that like
there's so many languagesthat express different things,
(25:11):
the API designer'sjob is often to think about how to get rid
of all that flavor and come backto really just the foundations of object
oriented principles, thingsthat are applicable in every language.
And it's a really tough set of constraintsto work with,
but it's kind of what makes it all work.
So yeah, right. Tricky for sure.
Yeah.
So, you know,we're, we're taking into account
(25:34):
all these, you know, sort of open APIand expressing things and all that.
And, you know, I know one of the struggleshistorically has always been,
you know, you write down a bunch of rulesand standard and then you ask,
you know, all the developers in a companyand really large ones, it's
hard to even communicatethat, that, hey, do it this way right?
(25:56):
And to to
sort of produce this feelingthat a bunch of APIs
feel like one thing,They feel like one platform.
So but that's hard, right?
So like, what's your approach to sort ofbuilding that consistency of design?
Well, you mentioned guardrails earlier,and I think that's
that's an important aspect.
So when I worked at SAS,it was a very large organization.
(26:18):
So it was it was very hard to
have people kind ofhave the same mindsets,
which is really kind of what's necessary
if you want to havea consistent set of APIs,
you know, and we had marginal successthere, you know,
so, you know,we had kind of API design standards.
We said, you know,you should do it this way.
You should avoid this particular practice.
(26:38):
This is how you should name thingsand things like that, you know,
which only goes so faruntil you can really
you can't codify a mindsetin an API style guide,
but youcan certainly try to communicate again.
And really the best way to dothat is two examples.
Now at Aperture, it was it was muchsimpler job because I was for a long time,
(26:59):
for four years
I was the only API architect,I was the only person designing the APIs.
So I, you know,I was able to just kind of use
the same style throughoutand had that consistent voice.
It's good to be the king, right?
I'm sorry.
It's good to be the king.Yeah, yeah, yeah.
But but even even over time,you know, that that voice changes.
And I can see where
(27:20):
there arethings that I designed for years ago
that were designedcompletely differently today.
And that's a really hard thingto, to really manage,
especially for a larger organization.
So but the best way to gois, is try to, to, you know,
keep in mind,you know, who you writing these APIs for,
they're they're written to be usedand written to be consumed.
(27:42):
They're not writtento be put up on a pedestal and say,
look how beautifulthis API is, isn't it elegant looking?
Right.
The real judge of that is can developerssolve problems with the API?
Can they actually consumeit and use it? Can they
adopt it quickly?
Do they know how to use it?
Can they infer how to use itbecause it's consistent, for example?
(28:05):
So if you do something in one place,the way you do pagination, one
part of the API should be the sameas what you do in another part of the API.
So selling people on that and really wantstheir software to be used.
So in order to get people to kind of buyinto any kind of governance product
or a program or anything like that, it's
the same thingas with user interfaces, right?
(28:25):
If it's inconsistent,
it's going to be harder for people to use.
It's not going to be as successful.
Somebody wants their stuffto be successful.
They want their APIs to be used.
They want to use interfaces and programsand applications to be used, etc..
So that's the primary thing, iscan you solve real problems with it
and can you get the feedbackfrom those consumers and developers
(28:48):
early enough to tell youyou're on the right path?
Or at least later on you get the feedbackthat yes, I am using it
and it is successful and then you use thatas a showcase for other people.
So when you have new peoplecoming into the company,
you can point them to your historyand say, You know, this style of API
works really well.
This one that we put out theretwo years ago, no one's really using it.
(29:11):
You know, maybe it'sdesign is isn't really kind of
doesn'treally meet the need and things like that.
So there's a lot of good informationcoming about now around governance.
So I know I know Laura over at Postmanis doing a lot of stuff
writing about governanceand he takes a, you know, kind of a
I don't want to say it'sa non-intrusive approach to governance.
(29:34):
It's really you have some guardrails,but you're really trying to lead
rather than push,you know, lead by example,
rather than forcing peopleto go down a specific path.
But basically, if everybody is on boardwith with the goals of the organization
and why you're doing this work to beginwith, then then that's really
what you used to incent people to,to come up with good consistent APIs.
(29:59):
Yeah.
And you had mentioned and written
about kind of,you know, thinking in dry terms, right?
Don't repeat yourself.
And I think that's a big partof what you're describing here.
And I like to express it that
your code base being
dry is far less importantthan the community of consumption
(30:20):
around that APIand how drive that code is set.
To your point on, can you canyou have common consistent patterns
that are used across
the whole portfolio of APIs means thatthe clients are using more than one API.
Just write up a bunch of their code and
you know, working at like pay per hour.
We have like a million developernetwork, right?
I'm like, you add one line of code to thatand you just added
(30:44):
10,000 lines of code next monthfor all the clients writing against us.
So if it's harder for you, fine.
Like that's the way I think for the broadaudience, because at the end of the day,
their time is more valuable than oursin terms of growing the business.
So that's that's an important that's animportant point because I have to kind of
sometimes clarify it to the engineerswho are building the APIs.
(31:07):
You know, they asked me,why do you make my job so hard?
And same because we're tryingto make the developers job easier,
you know, making the APIs easy to use
pays over multiple times in the effortthat we put forth initially.
You know, and a good example of that is sowe adopted
our see was a 4707
the problem plus JSON application problemplus JSON standard
(31:31):
for, you know, a standard error responseor they call it a problem response
because it doesn't have to be an error,could just be a problem.
And we adopted that pretty early
in our in our current cycle
of of new APIsthat we're doing for our platform.
And you know, we,we use it, but we extended it
so you know you have these
(31:52):
types deal on the air, which is a URLthat describes what that type means.
And so we have lots of different waysof expressing lots of different type
types of errors. So when you have a 422
that says unprocessed entity,right, syntactically valid.
But but there's something inside of itthat I can't deal with.
It's,it's internally inconsistent or whatever,
you know,So we have lots of different error types
(32:14):
that can be associated with a 422And sometimes people think
it's really kind of hard to manage
all those in the code base and generateswrite errors and things like that.
But, but it yieldsso many benefits to the developer who,
if you just returned back 422without explaining why
they're just lost right inor if it's a 400, why is it a 400?
(32:35):
We'll give them some hints.
And what we even do is we go beyond justdescribing what the areas with the detail.
We also have like a remediation thing.
How do you actually fixthis particular error?
So with every error type that we have,
we also have remediation that sayswhat you can do to to rectify it.
And that's there for the developersto make the developers job easier
so they get back reasonable errorsfrom the system
(32:58):
rather than just generic things that don'ttell them any information at all.
And the other part of this is,as you said, consistency.
So since open API is a standard document
format, we also have a whole bunchof templates that we use
and we have a tool to generate openAPI definitions from from these templates.
So you can really bootstrap an entire API
(33:20):
by just adding a couple annotations
to say, okay, I've got a,
I've got a resource here and I want togenerate some basic crystal operations
or I've got another resource over here andI want to add some actions to modify it.
Or here's a singletonobject over here, doesn't
have all the crystal operations around it,but it but it's managed this way.
And so we have a
(33:40):
we have, you know, five or sixdifferent patterns that we can express
with a simple annotation.
And then and you just code that brieflyand push a button and it generates
all the kind of standard boilerplatearound all those operations
and it puts in the security requirementsfor each of the operations
and it puts the tags in there and it givesyou response and requester response
(34:04):
schema placeholders, and it just generatesall this boilerplate for you
and then lets you work onwhat's important, right?
Because all that boilerplate, all thatstandard stuff, that's always the same.
You shouldn't have to deal with.You shouldn't have to write that.
You shouldn'teven have to copy and paste it.
But something else, do it.
And that's what this tool does,
and that gives you a standard layoutfor all of your APIs.
(34:24):
And then you just have to kind of fillin what's different,
adding new query parameters
to this operation or define youryour schemas over here, etc..
And then you can concentrate on the moreinteresting parts of writing an API,
which is really kind of what you're doingand what what the messages look like.
All right, I'm going to have to talk youinto give me a demo of this thing.
Letter. It sounds cool.
(34:46):
Shout out to Eric Velda, a
wild for for the Anglicized pronunciation
friend of the showwho helped develop that.
The problem detailsfor each of the papers.
And I totally second that advicelike don't make up error models. It's
so hard to do from scratch and I reallyfeel like this solved the problem.
(35:07):
And it's like the number one thingpeople screw up when they first build
an API is don't think better. It's so.
Wonderful.
Yeah, it's it's, it's a standard like memethat we see on all these different forms
APIs is return of 200 error equals true.
To totally don't break the basic rulesthat.
(35:27):
HTP API.
Yeah cool.
So I guess as you knowwe're kind of hit in time here.
I'm sure we're losing listenerswith boredom and other things to do
and any other sort of parting wordsof for us here.
And I'm always empathetic to folks
listening who are like overwhelmedby all the things you just said to do.
(35:50):
Where would they get started? Yeah.
So we're really fortunate in thatthe API community
is so open and accepting.
So there's lots of different placesthat you can jump in.
There's a lot of different Slack instancesout there.
APIs you won't hate is a good one.
There's Discord servers and stuffand then there are conferences.
(36:13):
So API days is going next week.
I'm not going to thatbut but Aaron, our API architect is
but there's API specification conferenceusually in the fall every year
hopefully they'll they'll do that againthis year.
I haven't heard anything about that butget involved with the community in one way
or another and follow what's going onwith the open API specification session
(36:34):
and project moonwalk,which is, you know, the next version,
the next rev of that specification, jumpin and make your voice heard.
The more
perspectives that we have, the better offthe environment is going to be.
But there's so many peoplethat you can call on and,
and if you don't have someoneat your own company that can be a mentor,
(36:54):
you know,
look outside your company and reach outin those other communities and say,
hey, I'm kind of new at this.
I know there's a lot to learn.
Is there anybody who could kind of help me
walk through my journey with meand help me grow
and understand, you know,the good ways of building an API program,
the good ways of designing an API,the good ways of of gathering requirements
(37:18):
and sharing that align and define facewith my product team.
You know, how do I succeedwith all these elements of API design?
There's a lot of people out there
reach outand as I said, they're very welcoming and.
People really dowant to help each other out.
So join the community.
Don't don't be afraid of jumping in
(37:39):
and you'll probably reap lots of benefits.
Of that advice. It's instead true.
I think it's part of what suck me intothe API vortex is just,
you know, I don't know.
People speak my language,you know, and people who somehow
if if they stay in it, have thisinnate will to try to describe the world.
(38:00):
Right?
This is what we've been talking aboutis now
that APIs are everywhere,we have to describe the world.
So how do we do it?
How are we going to put our headstogether?
Charlottesville surgeon for his API,As you will hate
former stop writer and regular contributorLevy you feel
well, David, thanks so much for being on.
Tell folks where they can find outabout all your writing stuff.
You're kind of mentioned in there,but where do they go?
(38:20):
Find it online.
Yeah, so it's on APIdesign matters, dot substack dot com.
It's all one word.
So the general the general Substackis called API design matters.
So it's all mattersrelated to APIs large and small.
And right now this,
the series that I'm doingis the, the language of API design,
but that's just a short seriesthat'll conclude.
(38:41):
But the broader one, it's just API design
matters.
Not well, thanks for sharing everythingwith the community
and we'll all follow along.
Except for Schade.
It's been a pleasure talking with you.
Thanks for listening.
If you have a question you want to ask,look in the description of whichever
(39:01):
platform you're viewing or listening onand there should be a link there
so you can go submit a questionand we'll do our best to find out
the right answer for you.
API Intersection Podcast listeners
are invited to sign up for Stoplightand save up to $650.
Use the code intersectionten to get 10% off a new subscription
(39:22):
to Stoplight Platform starter or pro.
Take a look at this episode'sdescription for more details.
Popular Podcasts
Dateline NBC
Current and classic episodes, featuring compelling true-crime mysteries, powerful documentaries and in-depth investigations. Follow now to get the latest episodes of Dateline NBC completely free, or subscribe to Dateline Premium for ad-free listening and exclusive bonus content: DatelinePremium.com
24/7 News: The Latest
The latest news in 4 minutes updated every hour, every day.
Therapy Gecko
An unlicensed lizard psychologist travels the universe talking to strangers about absolutely nothing. TO CALL THE GECKO: follow me on https://www.twitch.tv/lyleforever to get a notification for when I am taking calls. I am usually live Mondays, Wednesdays, and Fridays but lately a lot of other times too. I am a gecko.