Subscribe
Share
Share
Embed
Building a successful API requires more than just coding.
It starts with collaborative design, focuses on creating a great developer experience, and ends with getting your company on board, maintaining consistency, and maximizing your API’s profitability.
In the API Intersection, you’ll learn from experienced API practitioners who transformed their organizations, and get tangible advice to build quality APIs with collaborative API-first design.
Jason Harmon brings over a decade of industry-recognized REST API experience to discuss topics around API design, governance, identity/auth versioning, and more.
They’ll answer listener questions, and discuss best practices on API design (definition, modeling, grammar), Governance (multi-team design, reviewing new API’s), Platform Transformation (culture, internal education, versioning) and more.
They’ll also chat with experienced API practitioners from a wide array of industries to draw out practical takeaways and insights you can use.
Have a question for the podcast? DM us or tag us on Twitter at @stoplightio.
Everybody
wants their stuff to be successful.
They want their APIs to be used.
They want their user interfaces
and programs and applications
to be used, etc..
So that's the primary thing, is
can you solve real problems with it,
and can you get the feedback
from those consumers and developers
early enough to tell you
you're on the right path?
I'm Jason Harmon
and this is API intersection,
where you'll get insights from experienced
API practitioners to learn best
practices on things
like API design, governance, identity,
versioning and more.
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 time
as I like to go read and learn new stuff.
But every now
and then when I do get the chance,
there's people I trip across that
I just think I want to meet these people.
So our guest today, David Biesack,
I hope I said your name right.
I forgot to ask before. All right.
Chief API Officer
-cool title at Apiture
is 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 yourself
and what you guys do.
Yeah, thanks for inviting me.
So I'm Dave Biesack.
I as Jason mentioned, I'm
the chief API officer at Apiture.
I joined the company when it was founded
a little over five years ago
and they set out
to become a banking API platform.
So they want to build APIs
around their banking solutions
and brought me on board
to help build the API program there.
So I started out as an API architect
and then eventually moved up to where I am
now as chief API officer.
So I'm responsible for the design
and architecture of our APIs.
Most of the time I spend in doing that
analysis and design,
I work with the products
folks who come up with feature requirement
and then we map them into APIs.
And then I do API design along
with another API architect on the team.
His name is Aaron.
So we convert all the basic feature
requirements into APIs
and then the engineering teams
go in, implement all those APIs,
deploy them and help us secure them, etc..
So most of my work is around
designing those APIs,
but all the ancillary things
that go along with that as well.
So training other folks on what it means
to be an API first company
and what it means to,
you know, tried to design APIs upfront.
And really what we do
is try to gather those requirements and
make them separate from
just UI requirements or API requirements,
but just be feature requirements
and then build APIs around that.
So I've been doing that ever since.
Very cool.
You're you're are people, you're amongst
good company.
I think there's a lot of folks like,
you know,
trying to do
the 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 years
before coming to Aperture,
built a whole career there,
doing all kinds of things.
But I spent my entire time
in R&D organization.
When Java came out in 96,
I helped SAS adopt the Java platform.
So I was my role there was similar what
I do at Aperture as Chief API officer.
I was the R&D Java strategist,
so I helped define Java standards
for the entire organization
and did a lot of training on
Java adoption and building libraries
and 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 helped
all the teams design their rest.
APIs according to those standards, worked
on tooling around APIs
and things like that.
So it helped with the adoption of of APIs
throughout the R&D organization.
And in those five years,
we we had an API review process
and we had about 120 different APIs
that we brought through that
that design and review process.
While I was there. I
so I guess
bringing it back to kind of what
caught my attention as you had started
this blog post series
that you titled The Language of API
is that I think somewhat hubs around open
API, but I feel like
you touched on a bunch of other stuff too.
So I mean, kind of
what do you feel like is the big point
that you're working
to get across in the series?
Yeah,
so I've always been kind of a language
geek for my entire professional career,
so I was always interested
in programing languages,
as I mentioned, you know, helping
with the adoption of Java at SAS, etc.
I was always intrigued
by the expressiveness of languages,
how well they can capture your intent
as a developer, as a programmer,
how concise versus how verbose
those languages are.
New job is is kind of known
as a relatively verbose language,
but certain language attributes
can help improve
that with with type inference
and things like that.
But basically, how do they
how do they work as languages
for communicating ideas?
You know, our human language is used
for expressing ideas and communicating
with each other.
Programing languages are used
for communicating with the compiler
and the back end and the runtime, but
also for communicating with other people
who are going to be reading those programs
and reading that code later.
And so the idea of how
well you can express your ideas
in those languages is really intriguing
to me, and more
so how those languages change over time
and the way we use those languages
changes over time.
And in fact,
it comes to be that that oftentimes
those languages influence
the way you think about things.
So the solutions to a programing task
using
Java are very different from the solutions
you might come up with.
Using a functional language like Eve Sharp
or Scala or even TypeScript and stuff.
So that's what I'm really interested
in, is this notion of languages,
how they capture ideas, how
well you can express your ideas in them,
how they grow,
and how you as a programmer or developer
grow along with those languages.
As you acquire
those languages, become more fluent.
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 linguists
and just language geeks.
It's I feel like it's a it's
an occupational hazard of when you work
with APIs too much, all of a sudden words
take on a whole new meaning.
Yeah, I mean, like my favorite
example 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 means
you 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
from other practitioners
is the idea that the words
so you're
talking about kind of programing languages
and that expressiveness, which
is 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 greater
meaning
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 domain
definition 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 articles
that I wrote in this series.
I wrote about,
you know, using domain driven design.
And a lot of what we do
at 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 design
first is not API design first.
You know, everybody hears about API
design, API first, there's API first that.
But that's really a misnomer
or mischaracterization
because you don't start with the API
no matter what you're doing.
You have to go back
to business requirements
and 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 API
and really it's understanding that
and using the techniques of domain driven
design to characterize those problems.
And then an important part of that process
is building the ubiquitous language.
You know, what is the set of terms,
the vocabulary of your problem domain,
and then making sure everybody understands
and agrees on what those terms mean
so that you're removing ambiguity as you
as you move forward.
You go through the rest of the process.
So it's really important
to build that vocabulary
so that everybody understands
things from the get go.
I mean, it starts with with that,
you know, the product requirements
and understanding the domain
in which this problem resides
and understanding what those terms are.
And then you have to codify those
in some way.
So they actually become names of,
you know, when you do API modeling,
they will filter down and often become
names of resources in your API model,
or they may become the names of
operations in your API model.
But, but
that's where I really want people to start
is is going back to the source.
What is the problem
you're trying to solve?
And then how do you capture that
with the language?
And you know, design patterns were really
popular thing 20, 30 years ago.
And really what's important about design
patterns was this whole notion of
of the pattern language,
which is what you use to document
the problems in the forces
and then the patterns that you use
to solve those particular problems.
And I like to see the same mappings
happen with with APIs
as they do with just general software
development is you build a language
and you have a way of expressing
either the problem set or the solution
set with with specific languages.
And some languages are good for that
and some languages need need some work.
But, but that's really what intrigues me
about this and understanding what
how languages influence people
in the way you think.
Yeah, I was.
I think when I've tried to describe this
to people, I'm like,
if, if you had to draw a very naive sort
of graph of the conceptual names of things
in what you intend to build,
and you just put it on a big marker board
and you walked customers in the room,
would they point and go,
Oh yeah, that's my stuff.
You know what they recognize is quickly
conceptually what it is
that they intend to do out of
just the language
without anything further diffuse.
And you mentioned kind of DDT is sort
of the methodology that you're using.
Are there any sort of specific tools
that make that process of aligning around
language easier for, you.
Know, specific tools?
You know,
James, in his book, he outlines some
some 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 versus
we as a wiki primarily.
So our product team uses various
tools that that product managers
like to use for capturing,
you know, epics and higher level goals
and things like that.
So this is what this product
or this feature is going to do.
And then they break it down
into components
and they use various tools for that
and eventually things filter down
from from that method down into things
that become, you know, JIRA tickets.
We use JIRA for tracking
activities and our our
sprint cycles and things like that.
So a lot of things
come down as as JIRA tickets.
But what I do is
I have to consolidate all that information
from all these different sources, from
interviews with with the product people.
And we we sit down
and have meetings and we go over
and ask questions and things like that.
And then we just basically capture
everything into an API model
that we capture
just on a confluence page as a wiki page.
And it's very easy to collaborate on that.
So we can we can go in here
and we can kind of give a high level view.
What I do is
I do this translation exercise.
I take what they give me
as product requirements and then
I rephrase it
and kind of speak it back to them and say,
Is this the right way of picturing this
or representing this?
Do I have all the elements captured?
Is this a correct representation
of what you've told me?
And we iterate on that.
And because when I write things down
this way, then it will of course often
raise a lot of questions.
And so I will write those questions down
and then we can iterate on that confidence
page and people can add questions
and write responses in there
and then evolves over time.
It it's pretty easy to to modify
and extend that API model
as we learn more and more.
And the topic that the top of the document
is where I list,
you know, the vocabulary and list
what are the common terms for this
domain model?
And we make sure people have
a kind of understanding of that.
And then that filters down into the lower
level
of what
those API resources are going to be.
And that's tends to work
really, really well
versus something like JIRA, which tends to
fragment your knowledge
and put in lots of different places
that it's oftentimes
really hard to get the bigger picture
of how things interrelate.
You can have an epic
that's got 20 or 30 stories in it
and you have to click on each one,
open a page, read what's in there, read
the acceptance criteria,
and then go back to the next page
and 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 read
that initial requirement about this
one specific attribute
or 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
and is guided by again
with with domain driven design
as these bounded contexts that really kind
of 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 necessary
to pull that together.
And you can
certainly have related resources
and you can have sub resources, etc.
and you can explain all that.
But usually that that one wiki page talks
about that one specific domain model
and it tried to try to coalesce
all the information we need there
in order to then once we narrow that down
and we got the basic
API model worked out,
then we can transcribe that directly
into an open API document and start
building that and that becomes more of,
you know, the design art
of how you capture that into one
or more API documents.
We have a multi document design,
so we have a, an API
that's just called common,
which is one open
API document that has a bunch of common
reusable components.
So we've got schema components in there,
We've got standard
query parameters that might be used
elsewhere, we've got
standard response objects
and 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 accounts
in your account balances
or it's a transfer's API
for making transfers or transactions
API that lets
you look at those transaction history
for individual accounts and various
other elements.
You know, we do digital banking, so it's
all kinds of banking related resources.
Each one of those will have its own
API model and so an API definition,
an open API, but they can reference
schemas and other things from each other
quite naturally.
And that works really well
with the composition model
that's supported with open API.
Yeah, for sure.
And I got to double down here and say
that,
you know, we're certainly big fans
of James Higginbotham in this process.
And you mentioned ADR
and this is a lion defined design refine.
And I think what a lot of what
you just described is kind of the align
and define part, right?
It's like before you internally
it stopped by you know,
we tend to refer to this
as like the homework that happens
before you design.
And it's like a lot of it is just marker
boards 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.
It's about the discussion
and about the alignment
and having a user definition of it.
Yeah, it's very much communication
is just so, so central and key to that.
And the notion of collaboration
is really, really critical there.
Yeah,
because it's,
you know, when I worked at SAS SAS, it was
and is hugely based on analytics, right?
That's their bread
and butter is analytics.
But I never really learned
or became an analytics expert.
I didn't really know the domain model
very well.
I just I just kind of knew APIs
and interfaces
and kind of software design.
But all the work that I did as asked
really wasn't analytics based.
There were a lot of other
people 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 company
without any banking experience at all.
So I relied very heavily
on the domain experts
to teach me the domain ideas, you know.
And so I learned quite a bit
about banking,
but I'm not a banker
and I'm not a financial person.
I'm an API person.
But it's important
for 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 APIs
or they don't know good ways to structure
and manage an API program for evolution
and things like that.
And so it has to be teamwork there.
And we kind of teach each other as we go
along.
Yeah, I think it's one of the funnier
aspects of working on kind of,
you know, platform engineering
APIs 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?
It's everywhere.
It's in everything.
You know, your fridge
and your washer are talking.
This stuff.
You know, we're reminded of this
a 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
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 away
with a better understanding of it.
But if someone said, you know, describe
how the payment stack of the world
works, I'd be like,
I'll tell you to talk to you.
But, you know,
I trusted them in the definition
and just created the right guardrails
so that it looked and smelled
and 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 expressiveness
and kind of how to define these domains.
But I guess you mentioned in the course of
that open API is sort of the way
that you're expressing those things
and sort of
kicking 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 representation
of how to capture an API design.
There were lots of other competing
standards at the time.
You know, there's Ramle and there's API
blueprints and all kinds of other things.
But but Open API
kind of had the momentum going in
an open API 3.0 had been out
and the tooling around
that specification
was really kind of the kicker.
You know, by having a
well defined and constrained language
for expressing an API design
really enables the tools and stuff.
So I have lots of issues with open API
that I would like to change if I could.
But you know, there's lots of ways
that I would really like to extend open
API and it goes back to
I think if you go back to like issue like
182 and the GitHub repo is one an idea
that I put in there many, many years ago
that hasn't been adopted yet.
But there's a lot of people
who seem to like
that idea of just extending it
a little bit in a different direction.
But it's interesting
because it has constraints and
constraints are really kind of important.
You know, if open API adopted
everybody's wish
and made all these changes,
it would become untenable.
It would become unusable.
So those constraints are really
what are interesting.
And it was actually one of the
it was my last post
that I got and published on my my blog
and the Substack
was about growing a language.
And this is the 25th anniversary of Guy
Steel's seminal talk of the same name
I was recording. That was at the
OOP slot,
who was object oriented
programing systems, languages
and Applications and ACM conference
that was held every year
and they bring him to splash since then.
But 25 years ago he gave this really great
talk about growing a language.
And he was he was on staff at Sun
Microsystems at the time.
Java was was growing in popularity.
And there were all these requests
to extend job at this direction
or extend Java in that direction
to add this new feature here.
And he talked about, you know, how you go
about growing a language like Java
in this applies
directly to growing a language
like the open API specification
or growing a language like JSON schemas.
He talked about the forces
that come to play
and how you have to weigh all those forces
and think about the long term evolution
and what's going to be sustainable
and 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 does
any kind of software design,
especially around languages,
should really be familiar with that.
So so we adopted open API
and you know, haven't regretted that in
any by any means
because of the expressiveness that it has,
even though it's constrained.
Sometimes those constraints
are really helpful to help you focus
on what it is you're really trying to say
and with it with constrained language,
you can still have quite
a bit of expressiveness
and it's kind of nice
because it leads itself
to a much more consistent view
of what your APIs will look like
because you can't express completely wild
and crazy different things.
So anybody who's looking at an open API
definition understands its structure
and they understand the meaning
of all the constructs in that document
and and things.
So it helps
with, with the understanding of the API.
So that's what's really beneficial
about it.
In addition to it
being, you know, adjacent document
that can be passed
and processed and analyzed, you can use it
for co-generation,
you can use it for for creating marks,
you can use it for creating your,
your documentation
and you can use it for creating stickers
and all manner of deployment
methods and everything else.
So it's really beneficial there
and it's proven to be pretty powerful
and expressive
given that constraint that it has.
Yeah, I mean, to some extent
what you're really describing
is the design by constraints methodology
applied to HTP in general, right?
Like Fielding was trying
to sort of express the possibilities
with HTP programmatically.
So I think it even goes beyond that.
I have to comment to on like the
maintaining open API and how hard it is.
I was actually part of the founding crew
on the Open API initiative
and alongside Ron Rutkowski was supposed
to be the referee for the group.
And yeah, when you see all of the world's
perspectives
on how to design an API
and have to make choices, it's hard.
It's really hard
and my favorite example is
stuff like Discriminator and Open API
and like the fact
that it's never really quite
worked right in any tooling.
For my money, it's like
it's probably should've never been there.
The yes, people want to do that,
but it's like every time I've worked
with folks on Why are you trying
to build a polymer morphic API?
Write something that changes its meaning
depending on what you're doing.
Usually there's a cleaner way to do it,
and I think even to connect back
to your earlier point that like
there's so many languages
that express different things,
the API designer's
job is often to think about how to get rid
of all that flavor and come back
to really just the foundations of object
oriented principles, things
that are applicable in every language.
And it's a really tough set of constraints
to 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
all these, you know, sort of open API
and expressing things and all that.
And, you know, I know one of the struggles
historically has always been,
you know, you write down a bunch of rules
and standard and then you ask,
you know, all the developers in a company
and really large ones, it's
hard to even communicate
that, that, hey, do it this way right?
And to to
sort of produce this feeling
that 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 of
building 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.
So it was it was very hard to
have people kind of
have the same mindsets,
which is really kind of what's necessary
if you want to have
a consistent set of APIs,
you know, and we had marginal success
there, 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.
This is how you should name things
and things like that, you know,
which only goes so far
until you can really
you can't codify a mindset
in an API style guide,
but you
can certainly try to communicate again.
And really the best way to do
that is two examples.
Now at Aperture, it was it was much
simpler job because I was for a long time,
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 throughout
and 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
there are
things that I designed for years ago
that were designed
completely differently today.
And that's a really hard thing
to, to really manage,
especially for a larger organization.
So but the best way to go
is, is try to, to, you know,
keep in mind,
you know, who you writing these APIs for,
they're they're written to be used
and written to be consumed.
They're not written
to be put up on a pedestal and say,
look how beautiful
this API is, isn't it elegant looking?
Right.
The real judge of that is can developers
solve problems with the API?
Can they actually consume
it and use it? Can they
adopt it quickly?
Do they know how to use it?
Can they infer how to use it
because it's consistent, for example?
So if you do something in one place,
the way you do pagination, one
part of the API should be the same
as what you do in another part of the API.
So selling people on that and really wants
their software to be used.
So in order to get people to kind of buy
into any kind of governance product
or a program or anything like that, it's
the same thing
as with user interfaces, right?
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 stuff
to be successful.
They want their APIs to be used.
They want to use interfaces and programs
and applications to be used, etc..
So that's the primary thing, is
can you solve real problems with it
and can you get the feedback
from those consumers and developers
early enough to tell you
you're on the right path?
Or at least later on you get the feedback
that yes, I am using it
and it is successful and then you use that
as a showcase for other people.
So when you have new people
coming into the company,
you can point them to your history
and say, You know, this style of API
works really well.
This one that we put out there
two years ago, no one's really using it.
You know, maybe it's
design is isn't really kind of
doesn't
really meet the need and things like that.
So there's a lot of good information
coming about now around governance.
So I know I know Laura over at Postman
is doing a lot of stuff
writing about governance
and he takes a, you know, kind of a
I don't want to say it's
a non-intrusive approach to governance.
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 people
to go down a specific path.
But basically, if everybody is on board
with with the goals of the organization
and why you're doing this work to begin
with, then then that's really
what you used to incent people to,
to come up with good consistent APIs.
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 part
of what you're describing here.
And I like to express it that
your code base being
dry is far less important
than the community of consumption
around that API
and how drive that code is set.
To your point on, can you can
you have common consistent patterns
that are used across
the whole portfolio of APIs means that
the 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 developer
network, right?
I'm like, you add one line of code to that
and you just added
10,000 lines of code next month
for all the clients writing against us.
So if it's harder for you, fine.
Like that's the way I think for the broad
audience, because at the end of the day,
their time is more valuable than ours
in terms of growing the business.
So that's that's an important that's an
important point because I have to kind of
sometimes clarify it to the engineers
who are building the APIs.
You know, they asked me,
why do you make my job so hard?
And same because we're trying
to make the developers job easier,
you know, making the APIs easy to use
pays over multiple times in the effort
that we put forth initially.
You know, and a good example of that is so
we adopted
our see was a 4707
the problem plus JSON application problem
plus JSON standard
for, you know, a standard error response
or 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 APIs
that we're doing for our platform.
And you know, we,
we use it, but we extended it
so you know you have these
types deal on the air, which is a URL
that describes what that type means.
And so we have lots of different ways
of 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 it
that I can't deal with.
It's,
it's internally inconsistent or whatever,
you know,
So we have lots of different error types
that can be associated with a 422
And sometimes people think
it's really kind of hard to manage
all those in the code base and generates
write errors and things like that.
But, but it yields
so many benefits to the developer who,
if you just returned back 422
without explaining why
they're just lost right in
or if it's a 400, why is it a 400?
We'll give them some hints.
And what we even do is we go beyond just
describing what the areas with the detail.
We also have like a remediation thing.
How do you actually fix
this particular error?
So with every error type that we have,
we also have remediation that says
what you can do to to rectify it.
And that's there for the developers
to make the developers job easier
so they get back reasonable errors
from the system
rather than just generic things that don't
tell 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 bunch
of templates that we use
and we have a tool to generate open
API definitions from from these templates.
So you can really bootstrap an entire API
by just adding a couple annotations
to say, okay, I've got a,
I've got a resource here and I want to
generate some basic crystal operations
or I've got another resource over here and
I want to add some actions to modify it.
Or here's a singleton
object over here, doesn't
have all the crystal operations around it,
but it but it's managed this way.
And so we have a
we have, you know, five or six
different patterns that we can express
with a simple annotation.
And then and you just code that briefly
and push a button and it generates
all the kind of standard boilerplate
around all those operations
and it puts in the security requirements
for each of the operations
and it puts the tags in there and it gives
you response and requester response
schema placeholders, and it just generates
all this boilerplate for you
and then lets you work on
what's important, right?
Because all that boilerplate, all that
standard stuff, that's always the same.
You shouldn't have to deal with.
You shouldn't have to write that.
You shouldn't
even have to copy and paste it.
But something else, do it.
And that's what this tool does,
and that gives you a standard layout
for all of your APIs.
And then you just have to kind of fill
in what's different,
adding new query parameters
to this operation or define your
your schemas over here, etc..
And then you can concentrate on the more
interesting parts of writing an API,
which is really kind of what you're doing
and what what the messages look like.
All right, I'm going to have to talk you
into give me a demo of this thing.
Letter. It sounds cool.
Shout out to Eric Velda, a
wild for for the Anglicized pronunciation
friend of the show
who helped develop that.
The problem details
for each of the papers.
And I totally second that advice
like don't make up error models. It's
so hard to do from scratch and I really
feel like this solved the problem.
And it's like the number one thing
people 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 meme
that we see on all these different forms
APIs is return of 200 error equals true.
To totally don't break the basic rules
that.
HTP API.
Yeah cool.
So I guess as you know
we're kind of hit in time here.
I'm sure we're losing listeners
with boredom and other things to do
and any other sort of parting words
of for us here.
And I'm always empathetic to folks
listening who are like overwhelmed
by all the things you just said to do.
Where would they get started? Yeah.
So we're really fortunate in that
the API community
is so open and accepting.
So there's lots of different places
that you can jump in.
There's a lot of different Slack instances
out there.
APIs you won't hate is a good one.
There's Discord servers and stuff
and then there are conferences.
So API days is going next week.
I'm not going to that
but but Aaron, our API architect is
but there's API specification conference
usually in the fall every year
hopefully they'll they'll do that again
this year.
I haven't heard anything about that but
get involved with the community in one way
or another and follow what's going on
with the open API specification session
and project moonwalk,
which is, you know, the next version,
the next rev of that specification, jump
in and make your voice heard.
The more
perspectives that we have, the better off
the environment is going to be.
But there's so many people
that you can call on and,
and if you don't have someone
at your own company that can be a mentor,
you know,
look outside your company and reach out
in 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 me
and 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
and sharing that align and define face
with my product team.
You know, how do I succeed
with all these elements of API design?
There's a lot of people out there
reach out
and as I said, they're very welcoming and.
People really do
want to help each other out.
So join the community.
Don't don't be afraid of jumping in
and you'll probably reap lots of benefits.
Of that advice. It's instead true.
I think it's part of what suck me into
the 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 this
innate will to try to describe the world.
Right?
This is what we've been talking about
is now
that APIs are everywhere,
we have to describe the world.
So how do we do it?
How are we going to put our heads
together?
Charlottesville surgeon for his API,
As you will hate
former stop writer and regular contributor
Levy you feel
well, David, thanks so much for being on.
Tell folks where they can find out
about all your writing stuff.
You're kind of mentioned in there,
but where do they go?
Find it online.
Yeah, so it's on API
design matters, dot substack dot com.
It's all one word.
So the general the general Substack
is called API design matters.
So it's all matters
related to APIs large and small.
And right now this,
the series that I'm doing
is the, the language of API design,
but that's just a short series
that'll conclude.
But the broader one, it's just API design
matters.
Not well, thanks for sharing everything
with 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
platform you're viewing or listening on
and there should be a link there
so you can go submit a question
and we'll do our best to find out
the right answer for you.
API Intersection Podcast listeners
are invited to sign up for Stoplight
and save up to $650.
Use the code intersection
ten to get 10% off a new subscription
to Stoplight Platform starter or pro.
Take a look at this episode's
description for more details.