Subscribe
Share
Share
Embed
This week on the API Intersection podcast, we spoke with Wesley Beary–Architect of Engineering Practices and Culture, previously at Salesforce Technology. We originally reached out to Wesley after writing about the history of API Style Guides, as he played a key role in publishing one of the first open sourced API standards. However, that was many years ago, and Wesley has continued to grow into a broader role at Salesforce after Heroku was acquired.
Focused on people, innovation, and learning, Wesley has been a part of Salesforce for over a decade now (including his time at Heroku). Using his technical background and focusing on API governance evidently led him to the organizational side of things. With hundreds of architects and thousands of developers, things can get muddled quickly without proper process, education and communication. And that's where Wesley comes in.
We’ve yet to have an episode where the lines of API governance blur with greater company standardization and company-wide process, it was definitely a unique insight into a very large scale way of doing things.
To subscribe to the podcast, visit https://stoplight.io/podcast
Do you have a question you'd like answered, or a topic you want to see in a future episode? Let us know here: stoplight.io/question/
--- 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). Valid until December 31, 2022
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.
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.
We'll come back to API intersection.
We are playing a little bit of,
I don't know, OG today, right?
A bit of a walk down
memory lane for myself., certainly
is where I came from when we asked Wesley
Beary to join us on the podcast
and talk a little bit
about some of his past with APIs
and some of the things he's doing today.
My co-host again, Anna, Anna, thank you.
And so
Wesley tell us a little about yourself
and then we'll kind of get into it.
Sure. Yeah.
I work for Salesforce.
Have for just over ten years now.
Most of that time was inside of Heroku.
So when I joined, that's definitely
where I was and that's where I was for,
I think six or seven years
really over the ten years. So
worked a lot on Heroku API
stuff, which is definitely what brought me
to the attention of you all.
I think and I think we'll have some things
to say about that.
Otherwise, I live in Iowa,
so I've worked remotely for Salesforce
the whole time I've worked there,
which is kind of interesting
in its own right, maybe and
farther relatively recently.
I mean, she's like three and a half now,
but it still feels like yesterday almost.
And when I was into woodworking,
into gymnastics,
among other things, kind of pretty
eclectic set of interests, I guess.
So I think that'll probably come out
as we chat more as well.
Nice.
Well,
I try to frame my mess out, but yeah,
I think we probably have some make
or empathizing to do there.
Sure.
Cool.
Well,
you know, we were kind of doing some
look back
on how sort of API style guides
in their current form
and certainly with our interests
around spectral and kind of the community
growing around that and automating
some of this stuff.
Know my time at PayPal.
One of the things we did
there is said, you know, let's,
let's take our internal guidelines
for API design and make some sort of,
you know, vignette of that
for external consumption
just out of the interest
that people doing these things
don't really
there's not a way to share it.
And at the time,
I was very inspired by Hiroki as work
and as I learned over time
that you played a big part in that
in sort of publicly
publishing some of these guidelines.
So I'm curious, most of all, first off,
like, you know, where did that come from?
And I suppose this was pre Salesforce,
so perhaps you didn't have sort of
the corporate overlord factor to deal with
that sometimes stops
these things from happening.
But, you know, why did you do it?
What did you learn from it?
All that stuff.
I'd love to hear all about it.
Sure. I mean,
where do you even start? Wow.
I mean, for me, a lot of the journey of,
like, just a lot of my like, I guess
career trajectory in some sense
really took off right around the start
of a lot of cloud stuff becoming a thing,
you know, is the original Amazon
Web Services came out, that sort of thing.
And so one of the things that I ended up
getting really involved in,
just because I was interested, you know,
kind of relating to this whole like maker
tinkerer, kind of esthetic,
like cloud stuff seemed really cool.
But boy, was it a pain
to figure out how to actually use it
when none of us were familiar with it.
All of this stuff was brand new.
I wouldn't say that a lot of it was APIs
or necessarily the most user friendly.
So just like trying to kind of
like figure that out. So one of the
things that I sort
of just like undertook in order to learn
that better was to start writing
API client libraries in Ruby.
And I started with us with especially
some of the services
that were not supported at all yet
there just wasn't a client library for it
because it was so new, like Dynamo TV
or other things that had just come out
and it eventually then
spread across to make them for more
and more of the obvious things.
And then like Rackspace
came out with their offering
and other people came out with theirs
and I was curious about those.
And so I started making clients for those
and then eventually built out
this whole suite of libraries
to support a bunch of different
cloud providers that has a somewhat
shared interface anyway.
That in and of itself is kind of a
sore spot, I guess, in
terms of how much of a common interface
you can really have
because of how different
the different cloud providers are.
But it's a it's a library
called Fog in Ruby.
And so from that whole experience,
I had the opportunity,
you know, blessing, curse,
I don't know some of those maybe to
be exposed to a lot of different APIs
that were kind of sort
of trying to do the same thing,
which was interesting in terms of
I guess being able to kind of build
my palette almost.
I guess it's like we almost need like API,
like wine tasting or something
and sort of like, oh, I note hints of rest
in this one
and there's just this little bit of,
you know, like graph influence
or something.
I kind of like that mix or something,
right?
So, you know, everybody has their own
kind of style and flavor.
And so I think a lot of that, you know,
this is the long way of me
getting to like
that really helped me to build
a sense of my
own taste and preferences
so that when it came time then
for us to really talk seriously
about within the context of Heroku,
what we were going to do,
how that API was going to come together,
what we did and didn't want.
I wasn't just like starting from scratch.
I had this sense of like, well,
you know, I've, I've looked at these like
ten, 15, 20 APIs and some level of detail.
I like that part.
I didn't like this part.
And then it was still,
I think, an interesting
exercise to go through the process
of trying to articulate
why I didn't and didn't like things like
that wasn't always as easy.
And that's really what a lot of the style
guide was trying to do is not just say,
this is what
we should do, because I say so, but more.
This is what we should, we should do.
And here is some reasoning as to why
I think that is the better approach,
and I don't think we got it all right.
But I think that, you know, putting some
kind of stake in the ground was helpful.
And for me,
there was a mix of motivations, too.
I mean, some of it certainly was,
you know, just me
trying to better educate my colleagues
so that I wouldn't have to be the one
that made every API decision any more.
Right.
That, you know, I could say,
hey, I wrote up as much as I could,
like how I think about APIs.
I know it's a lot to digest or whatever,
but like I want to be able
to refer back to that
and help you to learn how I think about it
so that you can think
more like that as well.
Or if I'm wrong, that you can call me out
and we can have a discussion
explicitly about what I think
you know, why I reason that way,
why that's not right, how we should change
it, that sort of thing.
And you know,
given my background
and how a lot of my coming up
and everything was based on open source,
like whenever
I can, I would prefer to do something
more publicly.
Like I've rarely found that to be
something that has many downsides.
I mean, there are challenges
sometimes in terms of maintaining
and keeping those things running
and supporting the community
that sometimes builds around them.
But for me, that's always felt worth it.
I guess that makes sense.
I think that's a perfectly adequate answer
and I just want to call out here.
This is very interesting
and that I think most people would say,
hey, if you came up with an API, you know,
a guide for how to design good APIs,
I think most people would assume
you built APIs all the time.
And what I find fascinating here
is it's actually
that client or consumer advocacy.
But like, here's all the things I tried
and all the things I didn't like that
I want to prevent
from having to interact with again.
I think it's super valuable
for folks to learn from listening that
I find that in a lot of especially
larger enterprises, they get all the back
end architects together
and they worried out over
you know, some technical faction aspects.
And it's like ask the people who use them.
Right? You might get a different look.
Yeah. Yeah.
And I mean, I think
we get stuck in that mindset
a lot in technology for whatever reason.
But like in a lot of other worlds,
you wouldn't expect that, right?
Like, I don't know.
Like, you know, touching on
some of my other hobbies.
Like I'm really interested
in like making chairs.
I haven't succeeded yet
and actually doing it,
but this is something
that I would like to do.
Like, I wouldn't expect that as someone
that's new to trying to make chairs
that I would just go and reason it out
and figure out the right way
to make a chair.
I'm going to go
and look at a bunch of different chairs
and see what I like
and don't like about them.
And that is how I'm going
to get to a hypothesis about what
a good chair might look like, right?
I don't think that working from it
the other way is going to end up
in a good result.
I mean, there's a similar thing
just like as in my experience
of like all programing,
if I try to go straight
to like the abstraction basically,
which is, you know, what
we're talking about really with an API
you should like is abstracting
how you interface this thing
by trying to go straight
to writing the abstraction
without working through a few examples.
First,
the abstraction is almost always terrible.
Like I really need to usually work
through two or three examples of something
to kind of see the shape of it
and then work backwards from there
to figure out what the right abstraction
is that's going to map to that shape in
a meaningful way.
And yeah, I think otherwise, you end up
painting yourself into a corner
and you know, similarly there's
just like a cost benefit
ratio kind of thing, right?
Like the cost to consume
another API is relatively low.
The cost to build
another API is enormous in many cases.
Right.
And the cost of a mistake in the two cases
is also way different.
Like I'm consuming your API
and I make a mistake.
Like,
who cares, right?
It's very recoverable,
like very low impact.
But if I make an API and release it
to the world, that is wrong.
I'm in for months, two years of pain
in one way or another, probably like that.
So yeah, I think that made sense to me.
Although you know, I guess
I hadn't really thought about it
in quite the terms that you spoke of it.
So yeah.
So I love this idea of like
finding the cost and benefit.
And my question was going to be,
how do you balance sort of that
flavor and style and innovation
and excitement with sort of a need
for more standardization and a need
for more consistency without, you know,
designing out innovation?
That's a tricky one for sure.
I mean, I think for a lot of this,
like it's a balancing act, right?
So like,
I don't think I should try to like
innovate or come up with a new idea
for every single part of the API.
But that doesn't mean that I can't do,
you know, 80 or 90% of it in a way
that seems relatively
straightforward and traditional
and then try some things around the edges.
So even in the context of the Heroku
API, we did some things that
are kind of weird and I
don't know if I would do them again
or whatever,
but they were areas where we were trying
to do something interesting.
So the way we do like pagination and stuff
is, is quirky I think,
and not really exactly
like I've seen elsewhere, although
I've seen things that are similar,
like it wasn't totally from scratch.
So, you know, like it's just I guess
you have to pick your battles, right?
Like,
I don't think having everything be new
and shiny in
whatever is going to be the best.
I mean, to some extent
it goes back to this
sort of like user experience
or like client development angle, right?
Like I don't want to have to completely
figure out your weird
not like anything else API from scratch
like that's going to turn me off
from even interacting with your service
at all.
Like I want some degree of familiarity,
but I also can appreciate when it's
mostly familiar.
But there's a little twist, right?
And in some ways I think it even helps you
to appreciate that twist even more like,
Oh, I really appreciate this difference
that you bring to this space
like that, that is.
And you know, again,
I think that's something that came for me
from consuming a bunch of APIs
that we're in a similar space, right.
To see the nuances between how Rackspace
or OpenStack or Google approached,
I don't know, like a blob store
versus how Amazon did it right
and which features they did
and didn't emphasize
and what was easy to do
and what was harder to do
and things like that.
So I guess I should have qualified earlier
that the time frame
that we're talking about,
because I want to give you a pass on
like the paging stuff because this was,
if I remember right, something like 2013.
So like verging on ten years ago now.
Yeah, that's not really true.
Yeah, there, there were a lot of things
where, you know,
I probably would have used standards
if there were clear ones around.
But there were a lot of cases
where there were a few things
that were competing
to become the standard.
And so we just kind of had to make a call
because we needed to move forward.
Yeah, and I
think that's that the relevant bit
to that story and maybe in a part of
answering your question in a
more like let's say
timeline sensitive way is the areas
in my interpretation here
you experimented with the areas
that were unclear as to what clear
expectations would be, right?
So like paging at the time,
I remember like it was there
were a couple of different ways
that people tended to do it,
and I think that's still true
to some extent.
But there is kind of a flavor
of what people like to see, right.
That is much more clear now versus eight,
ten years ago,
which I think is an interesting one, too.
To look back on
now is when you think about, well,
first of all, I should also qualify.
We've asked Wesley
to go on a trip down the history lane
with or memory lane with us, but
that's not really what he's doing today,
and we're going to get to that.
But if you had to, like,
go and do all this again today,
you know, do
you think
that would be a different exercise,
perhaps discounting
your obviously much greater experience
and then.
It's a good question.
I mean, I think it's it's it's tricky.
I mean, I was younger in my career
as well. Right.
And I think there is a degree to which
when you're earlier in your career,
you're more likely
to have a little bit of a chip
on your shoulder
or feel like you have something to prove.
So I think there are some parts there
where it's like
I wanted to show that I had the chops
or something to come up with something
that could do this in an interesting way,
as opposed to just doing the,
the more staid or whatever
the thing that existed before
that would maybe have been good enough.
Like I think there were some cases
where now
I would think harder about whether or not
those were battles
that I wanted to fight for,
some of those things
where they were quirky
or whatever, right to be like,
it's not that I don't have a reason
for doing this,
but is that reason really good enough
for me to go off and do this?
Like at the time I was like, Yeah,
because I don't know.
Again,
I think there was some extent to which
like I wanted to prove something right,
which
I think I've mellowed out a little bit,
or maybe I already proved some things.
And so now I don't feel
as much of compulsion to do that.
But I think there were
some places like that where
I might not have pushed as hard.
I don't know.
I also, I think
I'm a little bit more comfortable
with nuance
maybe now than I was at times then.
There are definitely some things
where I sort of like,
even if it's a little bit weird,
if we can choose, like if we can pick and
sort of explain one rule
and then apply it uniformly across
everything that we're doing,
that's going to be easier
because then we don't have to explain
exceptions, whatever else,
having had many more years of experience,
you know, like you see that
exceptions are inevitable really.
And so then I don't know that I would have
railed so much against that and pushed
back as hard, especially because
it's like that worked until it didn't.
Right.
There are cases where it was like, yeah,
we picked a good rule, this is great.
And then you're almost done with the API
and like there's that one more endpoint
or something
and you're like, Oh, this it's just
is totally untenable
for me to still apply this one rule here.
And so now do
I need to go back to the drawing board
and reconsider whether or not
it made sense to be so strict
about applying it everywhere else?
Because now I can't actually apply it
everywhere like I originally intended.
And that's, you know, that's tricky, but
I don't know.
There's not too many things.
I don't think that I would call out
and say this particularly I would change.
Like overall,
I feel relatively satisfied with it.
I think one of the things,
if I had to name something would probably
have to do with like how deeply nested
some of the resources were or weren't.
There were some cases where it's like,
I don't know, we can get into the, you
know, the nitty gritty of the Heroku API.
But there are a lot of things
that are like,
you can only address this resource if you
nested underneath that particular app.
And so then that ends up implying
basically that you have like
a compound foreign key
where you need to know the app side
and the idea of whatever resource
you need to reference.
But like there's
no reason why you can't look at that app,
that resource by its direct reference.
And so like having a top level version
of that that you can just directly access
and not have to reference it
inside of an app.
Seems like it would have been a better
experience in a lot of cases and simpler
like you don't have to construct.
It is like weird
if URLs and things and clients like that
just would have been probably
a better experience.
But of course,
like we came to this realization
after that ship had sailed to some extent
and like reining that back in
or supporting both options, it's
kind of a pain in its own right.
So that's probably one of the ones
that really caught me out of like,
oh, like there are cases where you really
basically it is a compound foreign key.
So sure, like let's make a huge URL
that has all the keys in it
that it needs or whatever.
But if you really have something
that has a unique identifier, like
just let people access it by that unique
identifier, more or less the top level.
And you know, all of today.
So yeah, I think
you touch on two principles that I've
worked with folks on on their API designs
many, many times over the years.
One is what you said, like don't force
a compound identifier on the consumer.
If you can do more work on the server on
their behalf to have a single identifier
like that's just when you're doing
when you're on the client side,
that's a no brainer.
And yeah, happens all the time
and yeah, once it's out in the wild,
you can't rule it back.
Right?
You already said that one before.
I wanted to back up a little bit though,
to a thing that you touched on earlier
about about yourself
that I think I find is true
in sort of managing engineers
in their earlier careers.
Is this sort of the ego versus need?
And I'm certainly guilty of this one,
too, right.
Is this kind of.
Well, this is what we need,
which looks a little boring.
So how can I spice
set up and put my mark on it right there?
I think this makes a great Segway
to maybe put our walk down memory lane
back in the memories
of I might circle back and ask another
question and I forgot, but that's okay.
So it's like these
days you're much more involved
in kind of engineering
culture ish, by the sounds of it,
the way it reads within Salesforce.
Now I'm curious, like,
how did you get from, you know, writing
Standard Style Guide, whatever
you want to call it, around APIs and
you know, the kind of developer experience
around Heroku into,
you know, kind of how Salesforce does
engineering.
Sure, there's
maybe more of a common thread in my mind
than is obvious.
I mean, I'm not sure that
that sounds obvious when you just say it
for me, really
a lot of my time
at like in my career in general,
but especially within Heroku
and Salesforce has been
identifying some underserved need
and then finding
a way to work on that thing.
So even when I initially joined Heroku,
the position that I negotiated for myself,
even though that wasn't
what they had listed on the listing
initially or whatever, was to just work
directly on the CLIA client.
Like the
CLIA client existed certainly
at that point people liked it pretty well,
but it was something
where people came in and worked on it
when something needed to happen on it
for their future.
And then they walked away again.
There wasn't like really an owner.
There wasn't like an overarching
sense of what the CLIA should be.
And so there were some inconsistencies
over time that had slipped into it.
Like you'd notice, if you look closely
between different commands and stuff,
that it's like those are more or less
doing the same thing.
Why does it have a completely different
like verb kind of in the CLIA commands?
Like, you know, that that doesn't make
that much sense.
Could be
just make this a more consistent uniform
experience so that it's easier to learn.
Basically, if you already know it,
it kind of doesn't matter, right?
Like you have the muscle memory
of whatever you can run the command.
But if you've never learned this thing
before, the more differences
there are between, you know, this things
called create and that things called ADD,
but really in effect,
they're doing the exact same thing.
So why do we call it two different things?
So that's what I started working on.
And then over time
worked on a lot of things, including then
from working on the CLIA.
I actually got a ton of experience
working with our Heroku API
because that was what I was interacting
with all the time and started to see that
in the same way that CLIA had forums
like the exact same thing
happen on the server side where somebody
needed something for a feature
and they added something to the API
and then they walked away again and
you know, that works.
Okay. Ish.
But you know, it's
not really a sustainable way to do things
and doesn't really end up
with a good uniform interface over time.
And so we also had
a lot of idiosyncrasies.
There are a lot of inconsistencies.
And after I had kind of
gotten things settle down and like
locked in a little bit on the seal,
I ended up transitioning over
then to the API team
and working actually specifically on
moving towards that public API.
What that would look like,
how we would do it actually
doing a lot of the implementation
as well as the sort of design aspects
did that for quite some time
and then coming out of that started
working more on
really in many ways
thinking
about some of the governance things.
I think that's
what kind of started leading me
more towards this culture stuff.
So in addition to some of this
sort of like API related governance things
like I wasn't designing every endpoint
anymore, other people were,
so how did we like help them to
not have
such a hard time doing the right thing
and make it not a painful process
and make it not take forever
that they can still add things,
but still have it be up to the quality
standards that we want to have it
be consistent in the ways
we wanted, that sort of thing.
That's also why we did the design guide.
You know.
And so through all of that,
then I saw that it felt like
there was a broader, more
general need there.
And that led to defining our process
that we started using internally
and helping
to run that defining set of things
for doing architecture, decision records
and just more general decision records.
And so anyway,
it was this sort of like iterative
step more and more towards
that more organizational side of things.
And I felt really like
there were a number of things
organizationally where again,
there were needs that just weren't quite
getting met, that
the things that fell in between the cracks
and especially like within broader
Salesforce, the way we were organized
is that we have architects
which are sort of like our most senior
individual contributors
and they are sprinkled
throughout the organization,
but technically dotted line up
to sort of the office of the CTO.
And so it ends up that
because they're distributed in that way,
there wasn't someone
that was really taking a holistic view
of what it meant to be an architect,
what that ecosystem was like,
what particular needs they had.
Like for any individual leader,
they're like,
I have two or three architects
out of my several hundred people.
I'm not going to give them
special treatment or worry too much
about what they need in particular,
but deal across the whole org
and you have a few hundred architects
then you're like, actually, this is a
the size of a population that like
could probably use some, some support. And
so let's think
about how we can make their life easier
and how we can help them
to be more effective. And,
you know, I think the other thing
that people don't realize
until we got into it more deeply
is that the things that make their lives
easier and help them to be more effective
are frequently not very technical.
Like by the time they've reached
that point in their career,
like they've got the technical thing
like locked down.
Like that's not the challenge really.
Like, really, it's more,
hey, it turns out as in senior
individual contributor,
you are part of the leadership
of the company, but you don't have
any authority, you just have influence.
And trying to direct
the way that we will go in the future
without that
is a challenge, especially if that's not
something you've done before,
if that's not your background,
if you haven't gotten some support
and thought about doing that, you know, so
that's kind of more and more
the realm that I'm in of like,
how do we get folks to be able
to take their technical knowledge and
be able to effectively advocate for that
to impact the direction that we're going
and to take advantage of what they know
and to really just move the company
forward.
That's a common challenge
that we hear from so many of our guests.
Is is do we have the mandate?
Do we have the the ability to do what
we're suggesting or recommending?
How are you solving
some of the challenges for them?
How are you solving challenges
for architects across your work?
You know, it's a work in progress.
Some of it, I think, is really
I think
from my perspective
anyway, a lot of it is thinking about how,
you know, it isn't that we need to like
bring in more external knowledge
for the most part.
Like we have a lot of the knowledge
we need inside the organization.
It just isn't necessarily connected
and it isn't necessarily very leveraged.
So it's like the whole sort
of like skeletons in the closet
kind of situation, right?
It's like somebody knows this thing
that would be really valuable to know
right now.
Can we find them in this situation?
Can we get them to then share that
in a way that's going to resonate
with the people involved? Right.
And so there's definitely a lot of it
that involves
making connections basically,
and getting people to
learn from each other
about what's going on
and about what works or what doesn't work
within our organizational contexts.
Right.
It's not a
here's a generic leadership book,
please read it and you'll be better off.
It's like, Hey, you've had to pitch
something to this leader before.
What resonated with them?
Or like what is really the bee
in their bonnet right now?
Like what is going to be the thing
that's going to land with them?
Like,
how can I pitch this effectively, right?
And really thinking about
more sort
of like coaching and apprenticeship
and things like that of like,
hey, I'm on my way to being an architect.
I don't want to just like suddenly find
that I'm on the architect diving board,
about to jump in and don't know
how I'm going to manage this.
Right.
I'd like to have like
a more general transition of like
starting at the waiting end of the pool
and getting a little bit deeper
and a little bit deeper as someone like is
there to make sure that it's safe for me
and that if I have questions
or need support, that I can get it.
So yeah, I think,
you know, we got by, but
as the organization grew, like just
getting by is
less and less consistent over time.
I'll say, I guess like
some people get by better than
other people and some people get by worse
than other people.
And there's also just like
I think from my perspective at least,
I have a lot of concern about like the DEI
implications of that, for instance.
Right?
Like, yeah, in many cases,
the people that get by more readily
and the implied state of things
are the people who look like the people
who've historically gotten by OC,
which is mostly a bunch of graying white
dudes, right
as we were talking about before, like,
you know, of, of whom I am one, but
so, you know, really like just trying
to figure out how to get those supports.
And in many cases I think they are like
person to person supports.
It's not a I'm going
to bring in this external consultant
and they're going to teach a class to you
and you're going to be better off.
It's a hey, we all have a lot
we can learn from one another.
And the things that we need to learn
actually
are the things that each other knows,
not the things
that some other magical guru
we find is going to know or something.
So yeah,
just kind of trying to connect the dots.
I'm focusing a lot on like community
of practice
kinds of things
and trying to really figure out how to
do that in a way
that will build these connections, help
that transfer of knowledge, but also not
be too much of an ask for people, right?
Like people are busy.
I know. I don't know.
Just want to say, hey, by the way,
can you just spend an extra
five or 6 hours
a week contributing to my community?
I promise it'll be worth it.
You'll love it, right? Great.
But to really kind of
balance, you know, how to make that
as easy as possible
to do, how to make it as obvious,
what the benefit to you in doing that is.
And then, yeah, just slowly
but surely hopefully build some momentum
behind that and get it to something
that can hopefully sustain and really
get that transfer of knowledge going,
get people supported, get them to be able
to make that transition up
through the levels,
get them to be more successful
at the higher levels, just the
just the whole thing. So
do you find that
some element of that
is that everybody's got their siloed
version of kind of company
direction and strategy and that
getting those kind of viewpoints aligned
that there's like synergy
and sort of teamwork that that emerges
from that that wouldn't otherwise.
Yeah, I mean, there's
definitely some challenges there.
You know, the we use this
process called beauty mom, which I think
does a pretty good job in particular of
like providing vertical alignment to us.
So usually like we're pretty well aligned
I think, and have a good understanding of
like if we trace upward
through our hierarchy
what that person wants,
like what our leader wants.
But that doesn't always
give you the context
to necessarily know if I have a team
that's kind of near me,
but reports out through someone else, like
what is it that their leader wants
and how does that relate to
what my leader wants? And if they don't
like line up, then what?
Because there's definitely some situations
and especially if there is the,
you know, like
it makes things like whether or not
we should build shared services.
A very fraught question sometimes, right?
Like, well,
we would love it if you would build
a shared service and support it for us.
Okay.
But like
does that really align with what
we're trying to do or does that, you know,
will that create sort of like drag for us
that now
we need to support this broader thing
than we really need?
You know, so
all of those kinds of things
that you might imagine, right,
happen in a large organization
and they're not insurmountable.
But sometimes you have to get creative
about who you need to bring in to,
you know, broker that conversation or
make sure that that conversation happens.
I mean,
I think sometimes it's just a matter of
at least
to get started raising that awareness.
I think sometimes it's easy for those two
things to just fall under the radar.
And I think that's one of the things
that I really hope
to do with some of this community stuff
is to better connect people
that are sort of like horizontally
in the organization where
I don't know,
I've suggested this to a few people
and I always feel
like it's a little bit weird,
but it's this notion
that like on some level, I personally
I'm not sure that I care that much
if we have duplicate implementations,
as long as we don't have like duplicate
efforts to learn the same lesson.
Like I feel like in some ways
that's the more costly thing,
like if you're going to build a service.
But we already know
exactly what all of the specifications are
and how it should work like that.
Duplication probably isn't really
that expensive to us and a lot of ways.
But if you're going to start not really
knowing exactly what the requirements are,
which let's be honest, is
how we approach my software
most of the time in my experience, like
and there's one group
that's kind of sort of trying
to figure out exactly what I should do
over here and a different group over there
that's trying to kind of
sort of figure out what it's going to do.
And they come to more
or less the same conclusions
by having all the same costly
trial and error like that
seems really like a problem
that seems like such a waste.
Like if you learn something
interesting about I don't know how to run
event based systems and not very many
of us in the company have done that yet.
Like, please help us to learn
what that important lesson was so that
you don't
just do that same thing over again.
And that I
feel like there is often a big gap, right?
Like because okay, I learn something like
where do I put it
so that the relevant people can find it?
How does this work?
You know, how do I even know
if anybody cares about this?
And beyond that? Like,
is taking the time
to put that into a presentation
or a report or whatever else,
like something that's actually recognized
and rewarded in the company.
Or should I just like go back
to having heads down
because that's
what's going to get you promoted?
I mean, it's not the only thing that
causes people to do things,
but it's a factor for sure.
So yeah.
And on the learning, I guess.
On the listener context, I mean,
these days, Salesforce is pretty big.
I mean, what's this
sort of number of developers
and or architects
that we're talking about here
that you're working on? The scale of.
A fine question.
I never exactly know.
That's a really, really big
it's a good answer.
Hundreds of architects
and thousands of developers for sure.
But I don't know the exact number of it.
Yeah, yeah.
Which is I don't know.
I guess my observation here
is like on some level
you're working on sort of organizational
and systemic design.
Now as it turns to sort of this API design
and the bigger the scale of the problem,
while it would seem obvious
that the generic things where there's
the exception seem to be the rule.
Sounds like that's the thing in common
here, right?
Yeah.
And I mean,
I think the other thing that is
I don't know makes sense to me.
But again,
maybe sounds weird to other people.
It's like there feel like
there's a lot of parallels.
Like a lot of what I work on now is sort
of like the interface of the organization.
Like how do we make sure that information
transfers between these groups
if they're trying
to make an important decision,
like what's a good effective process
for them to do that
so they don't have to just make it up.
And to me at least, that feels a lot
like the parallels you might see
between like a private interface
and a public API or something, right?
It's like,
hey, all of these architects end up having
to do kind of sort of these same things.
Like they shouldn't have to renegotiate
what their interface is among them
while they're doing this important thing.
Also, like, can we just kind of agree
that at least most of the time
this is a reasonable way to go
about doing that thing,
like making an important decision
and then just focus
on the actual decisions
and not have to renegotiate
that every time.
Because I think there's, you know,
just this sort of like text that you get
otherwise you don't realize it.
But it's like
if we haven't really like come into this
with an understanding of how this process
is going to go, we're inherently going
to have to figure it out as we go along.
And sometimes that will be good
and sometimes all we've got.
But it's always going to cost something.
It's always going to be a distraction,
it's always going take away from us doing
the thing that we came here to do.
But at the same time,
I don't want to be like so strict
that people have no autonomy, right?
So it's this balancing
act of like, where do we draw the lines of
making recommendations versus
requirements or mandates or,
you know, however that might work out.
So, you know, for me, I'm
a big fan of just like defaults, right?
Or it's like this is the default.
If you have a really good reason
to deviate from it, more power to you.
But when you do that deviation, please
tell us what you learned right like that.
That is a requirement
if you're going to deviate
is that I want to learn what you learned
whether that's we deviated
and it was great here's
why or we deviated
and it was a terrible idea.
It turns out we should have just used
the default like, fine,
you know, just help us to figure out
if the defaults are wrong
or if there's a better default
or if we should recommend
80% of time use the default.
But here's this other set of cases
that sometimes this other thing will work.
All right?
Like, again, just like
how do we keep capturing that knowledge,
shifting it around,
helping everyone to continue to grow
and progress?
Well said.
At the at the time that you were
looking at it sort of opening up the
these sort of Heroku API design standards
guide, style guide, whatever we call it.
Did you have sort of inspirations
that you were looking out of others
who had done something similar?
Like looking back at it now,
the only thing I could find was like White
House was the only other project I found
that had really done it at the time.
But were there other sort of public
things like this
that you were looking at back then?
Yeah, I think I also remember
seeing the White House stuff at the time.
I think right around that time
the JSON API stuff had been kind of
initially written.
So I believe I looked at that time
and that was one of the things
where it's like I like how you're
talking about this stuff generally,
but I don't necessarily agree
with some of your conclusions like yeah,
and I think that was similar
with some of the White House stuff
where it's like,
I really like that
there is something like this.
But some of the particulars aren't quite
what I think
is going to work for us or what
I think is more generally applicable
otherwise.
I mean, I was definitely keeping an eye
on a lot of the different schema
things, right?
And the progress of those.
That was also another place
where it's like,
if I had it to do again, I don't know that
I would make the same decision.
We just did basically raw JS on schema
because that was also a place
that was very unsettled and basically
everything was ending up just using JSON
schema inside of its overarching schema
in some way, shape or form.
And so we were just sort of like, well,
JSON schema seems like the common thing
and it can pretty much cover the bases.
So let's just do that very not user
friendly though unfortunately.
It's like kind of a pain
to work directly with Jason schema. So
see, I
mean I was definitely like keeping an eye
on what was happening in the space,
but there weren't a lot of other examples.
That being said, like, you know, we had
actually done a style guide for the CEI
at Heroku like, you know, style guides
for something that like it was
something that I was familiar
with trying to use, right, to say,
here are kind of our preferences, here's
what we prefer.
Here are good defaults,
things like that, to
just help people
to be closer to the same page.
So yeah, I don't know.
There were I think it's like a lot
of things like I often that I draw from
indirect things, right?
Like so it's not that
I didn't look at style
guides, it's just that there weren't
that many API style guys. So it got.
So I looked at other style guides
and thought about what seemed to work.
Well, there were not work
well what I liked about them and you know,
you have to be a little bit creative
sometimes to figure out how that maps
between the domains or whatever.
But that doesn't mean
that there's not still interesting things
that you can draw there.
All right.
Well, I think you confirmed
what I've been fishing for
and doing this little history dig,
which is I'm pretty sure
that that publication was like
the first of sort of a private company
or a company that published their own view
on stuff as opposed to like Jason API,
which was sort of,
you know, trying to be one of the spec
standards or White House being government.
I mean, that was certainly an important
innovation, but I just want to
I guess I have to say and on behalf of all
probably a lot of folks listening, that
that time era, I think was important
in that step
that you guys took with heroic you
you may not have realized
at the time was super relevant
to a lot of people and realizing,
yeah, we should share this stuff
and we should all start
moving toward common ways of doing things
that really led down the road of,
you know, certainly in our world,
that stoplight like,
you know, having this sort of programmatic
method of of lynching for these things
instead of having to write out a bunch of,
you know, big, lengthy tomes,
I think we're just reflecting on that
and realizing like and the actions
you took were really important back then.
So for me, to you and I think
the community, thank you for doing that.
Wow. Well, that's very
humbling.
I, I mean,
I put a lot into it.
You know, it's something that I cared
about and I was glad of the result.
But yeah,
I guess it can be hard sometimes to know
how much of an impact
it really does or doesn't have on people.
And I'm I'm glad that it has had
that positive impact.
That's very rewarding for sure.
All right.
Well, that feels like a good place
for us to wrap, I think.
And I guess, you know,
I promised we were going to we're going
to talk Epilog stuff here talking
nearly ten years ago for style guides.
But but I love
your your perspectives of a
very gritty, hands on reality
of the culture change that comes
with these kinds of things over time.
And what it's like building a vast
engineering
empire, right now.
So just really appreciate
all the transparency
and and how much you shared with us today,
I guess.
Any closing thoughts for listeners
to maybe kind of
wrap this up
or give them some words of wisdom?
I mean, I think
kind of, you know, looking back
and thinking about some of the things
we talked about, one of the big things
I think is just, you know, to
try to draw really diverse inspiration
from different things and places.
I think that's been really impactful
for me in terms of, like I said, you know,
looking at
lots of different cloud providers
to kind of figure out what I liked
and what I didn't like or looking at style
guides that weren't even API style guides
because they're still, you know,
like that's
what I'm kind of trying to design for.
Yeah. Like it's.
There's so much that I learned,
for instance, from just like,
don't make me think and other UX stuff,
even though
API isn't always thought
about as being like a you sexy thing.
I think it is now, but especially when
I was doing it, it didn't feel that way.
And so there were definitely
like all of these things where,
you know, I don't think that I'm like
some crazy genius or something.
A lot of was just sort of like,
Oh, that was a really interesting idea
over from this totally other subject.
How could I apply that here?
Oh, interesting.
Maybe I can try this thing
and maybe that will be better
and not quite the way
that people think about it, because,
you know,
we're all in our little echo chamber
or whatever. Right.
So I definitely recommend.
Yeah, I just like
thinking about how to apply
these weird things from other realms
because that's where I feel like
for me at least, where I find a lot
of these inspirations and I'm able
to really push the thanks for it. So
I love it.
I think, you know, my takeaways are like
kind of design
thinking approach to all the things,
whether it be an organization,
an API or whatever, right?
And to some extent like systems
thinking that being a subset of that
and that kind of diversity
of inputs,
both in terms of people and in practice.
Right.
And that is
that's fantastic stuff.
And really, I couldn't it couldn't support
more what you're saying.
So for listeners, pay attention.
I know she's talking about.
All right. Well, thanks so much, Leslie.
Really appreciated this today.
And thanks Santa again for co-hosting.
Thanks for having me.
Yeah, thanks for having me.
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.
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.