Full transcript
0:00Jason why don't you give us a quick
0:03introduction to yourself
0:05and your background why we should all
0:07listen to you
0:09and what's all that stuff behind you've
0:10got an old typewriter and oh I know it's
0:12a mess I actually cleaned up a little
0:14bit this morning but I don't know
0:15everyone uh that I work with you know
0:18we're fully remote so on Zoom everyone
0:20enjoys all my hobby crap laying behind
0:22me so I get lazy about it anyway I'm
0:25Jason uh CTO at stoplight.io we're a
0:28collaborative API design platform you
0:30can kind of think of it like a figma for
0:32apis uh but beyond just the design and
0:36kind of no code experience we also have
0:38a lot of kind of governance features so
0:40folks looking to do Platform
0:42Transformations or sort of API products
0:45are typically coming to us to help kind
0:48of build those programs
0:50um
0:52I'm in the Austin Texas area since we're
0:54doing the location thing I guess yeah I
0:57don't know was there any other questions
0:59the question was miniature Hobbies my
1:01sons both love painting miniatures so
1:04they have like a giant cabinet full of
1:06all those like little mechs and DND guys
1:09and all that stuff I'm uh I'm currently
1:11on uh fpv drones so like you know flying
1:14a little quadcopter with uh with goggles
1:17on it's fun yeah I love it that's
1:20awesome
1:21um Alex uh share a little bit about your
1:23background please yeah sure Dan thanks
1:25so great to be here everyone so Alex
1:27Savage uh he and him I'm currently head
1:29of Integrations at Advanced which is a
1:31UK based SAS company so we've got a real
1:35variety of products across verticals and
1:38variety of products equals a lot of apis
1:40and we're really pushing that agenda of
1:43you know API first if you use a product
1:45you can use the user interface but
1:47there's also an API that covers that
1:49functionality you use as well so we've
1:51kind of been I'm going to say API
1:53obsessed for quite a while now and
1:55really feeling that Journey you've been
1:56talking to you Dan working with Jason
1:58and the team and their fantastic tool
2:01spot um stoplight and spectral hopefully
2:04we can we can find a little bit of time
2:05to talk about spectral probably one of
2:07my most used tools and yeah really here
2:10to learn something from Jason chat to
2:13you down and really find out what's
2:16going on there in the world what are
2:17people doing what are other people
2:18interested in
2:22Alex and I met by way of our spectral
2:25open source project and they're doing
2:27some of the coolest stuff with it uh
2:29it's it would be cool if everybody else
2:30got to see more of it but uh Alex is a
2:33smart guy
2:34yeah
2:35I'm I'm lucky to have uh uh these these
2:39two guys joining me here today so as I
2:41mentioned um there's a brand new course
2:43that we uh just published yesterday on
2:45Happy SEC you
2:47um created authored instructed by by
2:50Jason so you're learning really from
2:51from the the expert here on on API
2:56documentation best practices you can see
2:58uh it's about a two hour course uh you
3:01complete it you get a nice badge you can
3:02put it on your LinkedIn and show off to
3:04everybody
3:06um and it I'll talk and I'll ask you
3:09Jason here just a sec like
3:11um what uh what what what's sort of the
3:13agenda what you cover here in in the
3:15course itself but one thing that I found
3:17really interesting is this kind of
3:19intersection of governance and
3:22documentation right and when I think
3:24governance I think Alex when I think of
3:26documentation I think adjacent and I'm
3:28sure that's not fair but but you know
3:31um but what's interesting is security
3:33people we tend to think about like stick
3:36approaches to to achieving things right
3:40like we gotta plug something in we gotta
3:43put a monitor in there we gotta set
3:45rules and like you know beat developer
3:47represented creating this documentation
3:49and so forth and something that I found
3:52really interesting I was at a conference
3:54API days conference back in in New York
3:57a few months ago and there were these
3:59two guys from a big like grocery chain
4:03supermarket chain you know multi-billion
4:05dollar
4:06um shop and they needed to do the same
4:09things right they needed to get an
4:10inventory all their apis they need to
4:11make sure they were documented
4:13discoverable accessible and usable all
4:15that stuff and I kept waiting for them
4:17to talk about the stick approach
4:20um like when they went and they mandated
4:21and they you know shoved something in
4:23line and all this stuff and they never
4:25did that right what they did was they
4:28went around the deaf organization and
4:31the product managers and they just
4:33talked to them and they got to know like
4:35what what do we got running where is it
4:37what does it do and then what they did
4:39is they built a Marketplace and they
4:42said look you've got all these apis you
4:44know showcase them let's make sure
4:45everyone can use them don't have to
4:47reinvent bent the wheel and and make
4:50sure they're documented real well right
4:51and they turned an objective which is we
4:54need better visibility we need better
4:56controls standardization and made it
4:59actually something good for the company
5:01right and and so you know Alex maybe you
5:07know toss this over to you but like
5:09you're out there on the front lines you
5:10work with a lot of organizations this
5:13stick versus irid approach have you seen
5:16it and what seems to work better in
5:18Europe in your experience I definitely
5:21think the carrot's the better way doing
5:23it like you see the anti-patterns of if
5:25you're being the API police you're doing
5:27it wrong and really trying to put
5:30together a tool set and enable people
5:33you know as uh court and Keith Casey as
5:36developers we want to do two things we
5:38want to make brilliant things that are
5:39valuable when we want to go home on time
5:41so how do you turn up and say hey I've
5:43got some things that are going to enable
5:45that agenda help you write really good
5:47things that are going to work they're
5:48going to be robust and I think it really
5:50comes from that you know apis are not
5:52easy the fact that we've got so many
5:54people coming along today to come listen
5:56to us talk about apis I don't know if
5:58that would have been a thing five or ten
6:00years ago I think we talk about the kind
6:02of
6:03apis re-evolving especially around like
6:07the prolific use now of open API and
6:10that I think is one of the biggest key
6:12enablers for us we're saying we're going
6:14to do we're going to design apis and
6:16we're going to use an agnostic language
6:18we're going to use open API to describe
6:20what this API is like and then it
6:22unlocks all of these capabilities for
6:24governance and even like the automation
6:26of governance and so give me your open
6:28API and it comes through and says
6:30sorry you forgot to do security or sorry
6:33we haven't got any authorization
6:35and to be able to automate that and put
6:37that on a developer's computer on their
6:40machine or wherever they're doing their
6:41work
6:42one of my friends is meet developers
6:44where they are
6:45be their friend be like the little angel
6:47or the person whisper in their ear and
6:49you can get a computer to do that
6:50there's no ego there's no opinion I feel
6:53like you're teaching is there a red
6:54pinning so you did a bad thing red pen
6:56red pen it's just they're going what
6:58about that
6:59what about that and we have people that
7:02come to us and say like the the tools
7:03that we use they're a game changer
7:05couldn't do apis without it and so it's
7:07really about
7:09spending the time to to find people
7:12be amongst them exactly like your team
7:15there from the um from the supermarket
7:18find out what those pains are and fix
7:20them and then people will go away and be
7:22happy and they'll be successful and even
7:24if they don't come back to you all the
7:25time and say oh thank you again your
7:28tour so good if they're not coming
7:30complaining you know that you've had a
7:32little bit of impact in that person's
7:34life in that what they've done and you
7:36could be happy about it we kind of talk
7:38about in API land we're often we're the
7:42people that build the sets that let the
7:44lead actor or actress go and win the
7:46Oscar
7:47yeah you had a little part in that you
7:48maybe you should be on a little credit
7:50screen but think about how can I enable
7:52others
7:53and if they're successful they're going
7:55to keep using your stuff and then they
7:57become the the evangelists or the
7:58advocates for it and then the the train
8:01moves on
8:02and and appreciate that you know and
8:05Jason I've heard you say like you're not
8:07a security guy you're not a security
8:09company
8:11um and yet it's it have you been
8:13surprised how relevant this topic is to
8:16the security side of the shop and have
8:19you seen firsthand like this difference
8:21of approaches to to addressing
8:25um security from from uh from a
8:27developer perspective versus a security
8:29team's perspective
8:31yeah I mean I think first off I always
8:34have like the no known problems of like
8:36I've done this stuff for a long long
8:38time and I take things for granted
8:40sometimes and I definitely think the
8:42last year for us at stoplight has been
8:45sort of revisiting the topic of
8:47documentation because we just saw like
8:49this increased demand around it and
8:52we're trying to kind of understand what
8:54the story is
8:56um and I think the first real problem
8:58that everyone's trying to solve and this
9:02is you know there's another context
9:05thing right like
9:06five ten years ago Alex as you said it
9:09was like really Innovative companies
9:11doing interesting things with apis now
9:13it's like you know not to be derogatory
9:16here but like it's like the unwashed
9:18masses man like everyone's building an
9:20API for something now
9:21but that means a lot of people are just
9:23getting started and they don't know much
9:25right so when it comes to uh you've gone
9:29and you've tried or maybe you tried to
9:30be the Bezos right and make a mandate
9:32every one of us build apis and things
9:34will be great and then what happens you
9:37got sprawl right everyone built a bunch
9:40of stuff and nobody understands no one
9:43even knows it exists uh you know
9:45especially if you have you know uh we've
9:47had lots of reduction in force and
9:49things like that in different companies
9:50where the tribal memory is lost and so
9:53you've got these zombie apis that no one
9:56knows about no one understands
9:58and um
9:59in our world that's driven this
10:02documentation use case for folks saying
10:04look
10:05fancy governance things and all that
10:07stuff Alex is talking about you know
10:09automating your rules and having design
10:11review processes that's all cool and
10:13good but I think we've really embraced
10:15the idea that documentation is the
10:17starting point to control the sprawl
10:19problem which in simple terms is
10:22if we need to know what our capabilities
10:25are we need to build a catalog of what
10:28those things are and make sure that
10:30everyone's looking at the same source of
10:32Truth
10:33and I think Dan to your point on like
10:35how does this what does any of that have
10:37to do with security
10:38uh I think it's actually similar to like
10:42cloud observability and some of these
10:44other things where people are coming at
10:45it from the right and saying uh well
10:48we've got security breaches or you know
10:51we're trying to figure out from run time
10:53logs what exists all these things and
10:56looking for a silver bullet and anyone
10:58that's tried knows there isn't one and
11:00really the only way to get ahead of it
11:02all is to start from the left and really
11:06go figure out who's building what right
11:08now
11:09uh and if you built something before
11:11let's go just document it and put it all
11:14in the same place so we're all looking
11:15at the same thing and start engaging
11:18security all the way at that left side
11:22um which really I think in a lot of ways
11:24also leads to product development teams
11:26embracing the idea that step one in API
11:29development is roughly document what
11:32you're going to build and have an
11:33abstract design and open API
11:36which gives enough of a surface to have
11:38a security discussion in doing the
11:41course it really
11:42you know helped unpack all those ideas
11:45that again I think sometimes I take for
11:47granted that that everybody already
11:49knows because you know some folks have
11:51been doing it for a decade but most
11:53folks are just getting started well I I
11:55will just say we've the courses your
11:58course has only been up for 24 hours and
12:00I think we're north of 500
12:03um students enroll so I think you've hit
12:05a nerve
12:06um with this topic and and it's not just
12:10um developers and API owners but
12:13security people
12:14um interested in understanding how this
12:16all works and Tim thanks for your
12:18comment here um from the Salesforce side
12:20like on the sprawling sprawl is
12:22definitely a Hot Topic when it comes to
12:25apis in general and
12:28um I'm just sort of curious like you
12:30know there are so many approaches that
12:32people take I mean there's the there's
12:34the Stick of video camera on the network
12:36approach to addressing sprawl like all
12:39right let's just watch everything and
12:40when we see something that looks like an
12:41API flag it there's the supermarket guys
12:45approach like hey let's just go talk to
12:47everyone like you know what's your where
12:50do you land on on like you know imagine
12:52you're you're at you know a big company
12:54and uh you're the C so you need to get
12:57your arms around the the API inventory
13:01where are you starting
13:06yeah I mean I it's kind of one of these
13:08things where you know it feels like an
13:11argument between you know do you go
13:13build this enablement approach and
13:16engage with all the teams or do you go
13:18to the run time and try to figure out
13:19and I think this is definitely one of
13:21those situations where both is probably
13:23the right answer you can certainly
13:25figure out what already exists in some
13:28rough form by looking at your runtime
13:30environment
13:31um testing environments are also really
13:33good if you have a good testing culture
13:35but let's be real API testing is usually
13:38kind of a mess
13:39uh so you're probably looking at some
13:43form of you know getting to production
13:44log stuff
13:46but if you leave it at that there's a
13:49wave of new stuff getting built right
13:51now that your gateway is not going to
13:53show you your runtime logs are not going
13:54to show you and
13:57um you know there's duplication of
13:58effort that goes uh beyond the security
14:00aspect as well in folks not knowing uh
14:04hey we're all going after the same
14:05Market opportunity and building really
14:07similar things so all of that is to say
14:10you know built and suspenders like sure
14:13check the runtime stuff figure out what
14:15you got that's already out there and
14:16that's probably the top priority from a
14:18security standpoint but you can't stop
14:21there or you're just going to have the
14:23same problem again in the next couple
14:24quarters
14:25yeah I'm curious Alex if you if you see
14:28this in your world as well you know
14:31folks are struggling to get their arms
14:32around what they got I think so and we
14:35we did that initial moth pop we were
14:38very much like the supermarket one of
14:39Let's go and find out you know oasp API
14:42top 10 improper Asset Management it's a
14:44massive thing you know you can't protect
14:46what you don't know about so you go
14:47around and you ask everyone you say Hey
14:49you know security amnesty
14:51tell us what you got good bad ugly
14:53whatever tell us what you got and we'll
14:55look at it we'll give you a point of
14:56view I think the the future State and
14:59moving forward it's definitely got to be
15:01that that build that stadium with the
15:03with the walls and the guard rails and
15:06let people come and play and have a good
15:08user experience so I'm a big advocate
15:10for having like a API design Suite or a
15:13design tool and having that registry
15:15that says if you want to design an API
15:17use this tool if you want to find out
15:19about apis here's a tool and we're
15:21seeing the the kind of next evolution of
15:23that with big SAS players where before
15:26to be mature you'd like you'd have a
15:28status page and you'd have a some sort
15:30of I'm going to say documentation portal
15:33or something like redark that just says
15:35here's here's my documentation and now
15:37it's really evolving forward to being
15:39more of a we joke about it being like a
15:41car dealership
15:43you know lots of places have got these
15:44like if you you pause for a second
15:46imagine you know you drive past like an
15:48Audi car dealership and all of them are
15:50gray they're all you know they're all
15:52cars they've got four wheels but there's
15:54a sporty one there's a one for families
15:56and it's really that
15:58Evolution to say these things are safe
16:01secure performing attractive but they
16:04all cover these different use cases and
16:06they sit well together and that's really
16:08where these big players are getting to
16:09in terms of maturity so how do you if
16:12you're like entering this game and
16:13you're going okay what a good look like
16:15I'm gonna have a look at PayPal that you
16:17go
16:18Wow way like that is a really good API
16:21and it's used at scanner how do I aspire
16:23to that and it's definitely got to be as
16:25you said
16:26start small try and get that security to
16:30the left start having those
16:31conversations and ideally if you can I'm
16:34going to flip and say design document
16:36and Design
16:37you can definitely learn more and you
16:39will continue to learn more every day
16:42and you're only going to get better
16:45yeah that's been part of that aha that
16:48like
16:48you know I think of the design exercise
16:52uh as you know let's let's define what
16:55the end point is and what the fields are
16:56in the data and all that stuff but
16:58implicit and this is where I've had to
17:00just go you've got to be more explicit
17:02about this that design first you know
17:05designing things before you build it
17:07includes documenting it because you
17:10can't just have this sort of dictionary
17:12description and have any meaning to it
17:14uh so I think the idea of API first or
17:18design first whatever tagline you throw
17:20on it in some ways is all saying
17:22documentation first
17:25I am that's and that maybe goes to the
17:28sort of the point of the whole course
17:29right and then this of this topic right
17:31how does
17:33um how does API documentation enable
17:36security right so so obviously it's
17:38relevant and you cover it in the course
17:40right you've got these these different
17:42audiences for for your apis and maybe
17:46Jason actually this would be a good
17:48segue into kind of what you're what we
17:49cover in the course itself
17:51um I was just about to head into like
17:53who are the audiences who are the
17:54consumers of of the course itself but
17:57could you just you know give us this is
17:59straight from the course I'm grabbing a
18:00few slides here but this is like the
18:02agenda so you know walk through
18:05um for folks on the on the call here
18:07like what is it that you're covering
18:08here in the course why they might be
18:09interested in taking it
18:11yeah I mean I think the uh the what is
18:14API documentation thing is kind of
18:16really breaking down that a lot of times
18:18we think of what we put in that open API
18:20description which is usually like a
18:23summary description of what the API is
18:25and then describe all your parameters
18:27and Fields right that that's only one
18:30thread of it and that really
18:33kind of the bigger picture of what do
18:36all these apis do together why should I
18:39use this and what are my use cases
18:43um you know that takes a different level
18:45of content uh to really engage folks so
18:49um you know Alex you mentioned PayPal
18:51which um you know I worked there uh I
18:55was probably like eight years ago now
18:56and helped kind of do the V1 of the rest
18:59apis
19:00and it was a real eye-opener for me that
19:03sorry the dogs are going to be noisy
19:05here I apologize no worries
19:07um
19:08you know there were very clear examples
19:11everywhere that uh that one API is not
19:15going to be that useful so in the
19:17example of a credit card uh payment
19:19right which any fintech these days seems
19:22to have uh some engagement with that you
19:25have to get an authorization before you
19:27can execute the charge and in the middle
19:29you might need some third-party consent
19:31to do so
19:32so you have to describe flow right flow
19:36across multiple apis which by the way is
19:39a good lead into like that's how you
19:41should test them right testing each
19:43individual API in a vacuum they may work
19:46great independently but not when you put
19:48it all together
19:49um but for what it's worth documenting
19:51that first is a good way to set up your
19:54testing to build the right kind of
19:55scenarios right so that's kind of the
19:57whole what is API documentation is
19:59breaking down that it's more than
20:01reference material there's guides
20:03there's task oriented stuff
20:06um that can be really helpful and more
20:08than anything have a great getting
20:10started right
20:12um yeah business impact is really you
20:15know some of the stuff we were talking
20:16about here a little while ago that like
20:18how do you prevent duplicate
20:20um you know duplicated effort
20:23um you know just documenting things
20:25before you build them and putting it all
20:26in the same place is a pretty simple
20:28tactic and it works
20:30um you know looking at what's running in
20:33production is not going to tell you
20:34what's coming next and I remember from
20:37from this section of your course you
20:39talk about like some of the different
20:41constituencies right I think you got a
20:44security business impact the governance
20:46a you know partners and Integrations
20:49that's all that's all covered here yeah
20:52so there's a lot of angles to it I think
20:54it's funny I was actually doing a talk
20:56in the Bay area yesterday and we touched
20:59on documentation around how to treat
21:00apis as products
21:02and I was really explaining that like
21:04what's weird about managing as a product
21:06an API as a product is it's headless
21:09there is no point-and-click thing to do
21:11and in many ways the documentation
21:13whether you call it a portal or
21:15Marketplace or whatever
21:17um that is the head for your API in a
21:20sense that's how people know it exists
21:22that's how they know how to use it so
21:24from a product management standpoint
21:26it's a critical asset for the Myriad of
21:29stakeholders who benefit from it well
21:32and and I'll I'll just interrupt you
21:33here as for a little detour there but
21:35you know
21:37sort of my day job is is on the API
21:40security testing side right that's what
21:42we do at appisec and you know we work
21:46with a whole lot of pen testers and red
21:48teams and these kinds of things and to
21:50your point like you know testing a web
21:52app or a mobile app you're at least
21:54given a starting point right like this
21:57is what the app looks like these are the
21:59words these are the buttons you can
22:01press right there's a structure there
22:03but but pen testing an API is like okay
22:07here's your command line
22:09go to it right
22:12um and to your point like that document
22:14if you're a security team no wonder
22:16they're they're pulling their hair out
22:17right if there's not documentation you
22:19are really stuck right there's from a
22:22Security application where do you you
22:24end up spending most of your time
22:26reverse engineering
22:28what is this API what does it do let me
22:31just try calling a bunch of stuff and
22:33and or interacting with the web app and
22:35seeing what apis it happens to be using
22:37and so forth so so often with internal
22:40apis it's like there's no real
22:42documentation there's some Confluence
22:44article that describes how it was built
22:46not how to use it right which isn't
22:48terribly useful yeah
22:51yeah that's right so I like your point
22:53though like this is the the UI if you
22:55will
22:56um for a developer for a for an
22:59integrator for a partner and for the
23:01security team as well yeah
23:03um the the documenting a fake API
23:05together is obviously just kind of going
23:07through and actually doing it on
23:09something that we contrived I'll admit
23:11that there's a thing in there that
23:12drives me crazy uh I our component
23:16Library feature in stoplight's really
23:18new and I didn't quite understand how to
23:21update a change so where it describes
23:23the error object it's undocumented and I
23:26just didn't have time to go fix it but
23:28it makes me know and I apologize that I
23:29did a docs course with an undocumented
23:31Universal error object it's horrible
23:33well I will say though
23:36um it's pretty cool for folks I've been
23:38taking the course like you go do a live
23:40documenting of an API right there in
23:43front of you right and and we'll talk
23:46about it you know I think in a few
23:47slides but um you know how you know just
23:51don't try to like best practice don't
23:53document by hand right like there are
23:55tools there are techniques right
23:58um Alex I don't know were you were you
23:59jumping in there with with the comment I
24:02was just chuckling to somebody
24:04um Giovanni in the chat said about the
24:06protection of documentation and that is
24:08a fair point where you've got a really
24:11nice red carpet or map that says here's
24:14all of the things that you can do and
24:16we've got teams out there using Kite
24:18Runner and Discovery tools and trying to
24:20reverse engineering API so sometimes it
24:23is appropriate yeah to keep your
24:24documentation away somewhere that's
24:26internal only but otherwise you're there
24:29trying to you're trying to put that red
24:30carpet out there if you're doing public
24:33apis or or product to say hey here's my
24:36API you've got to put it out there with
24:38that with that guide and pulling on
24:40saying Jason said there that was the
24:42original like here's my open API
24:45definition or here's a rendering of it
24:47in HTML but it didn't tell you you how
24:49to get started didn't tell you how to
24:51get authorized and maybe had an email
24:53say you dropped Chad at such and such an
24:55email and maybe you'll get an API key
24:57and maybe maybe you will maybe you won't
25:00and really that Evolution on to say how
25:03do we get people going with like a
25:05recipe so you know here's the API these
25:08are the things you're going to use and
25:09let's bake something together and really
25:11funnel them through to seeing some
25:13success
25:15um I don't know if people have heard
25:16like the time to First hello world
25:17metric
25:19so you know how how usable is our API
25:21well we'll measure from somebody like
25:23arriving on the documentation portal to
25:26getting like a 200 back from Postman or
25:28something and you go yeah okay that was
25:29that was two minutes
25:31allowed them to sign up get credentials
25:34make a call get some success and people
25:36are going to be more successful going
25:38forward because like success breeds
25:40success so good documentation that tells
25:43the truth
25:44that matches the implementation people
25:47are just going to start walking and
25:48they're going to start running and you
25:50unlocked that capability and that meant
25:52that the thing that you invested in
25:54creating this API was well worth it yeah
25:57it sounds like you've taken Jason's
25:59course
26:00um because
26:02um guys before it's all pretty Common
26:04Sense stuff if you've done it and failed
26:06repeatedly like Alex and I probably both
26:08have well it's common sense if you've
26:10been there but like you know I had the
26:12pleasure of of you know helping edit and
26:14post your your course so I got to take
26:16it by virtue of doing that and it was
26:18eye-opening to me like the the comments
26:21around like if you're building an API
26:23like
26:24presumably it's because you want
26:26someone to use it right whether it's
26:29someone inside the company a partner you
26:32know the World At Large right and you're
26:35putting yourself out there right this is
26:37a product and I've heard this many times
26:39on many conversations like this like we
26:42need to start treating apis like
26:43products you should probably have API
26:46product managers right like make them
26:49first class citizens the the apis
26:51themselves and
26:53um and if you're gonna go through all
26:55that work right you want to have a good
26:57result you want your consumer your
27:00customer to like the experience right
27:02and and what goes into liking the
27:04experience well it was well documented
27:06there were some examples there was
27:09videos or how to's or all that stuff
27:12right Jason like that's all part of your
27:14course here yeah
27:17um
27:18I think you know beyond like the uh
27:21getting started and and Alex called that
27:24auth that's another thing we spend a
27:25disproportionate amount of time in the
27:27course on is making sure that you get
27:29that one like well I'll just say even
27:31beyond the course if you're building
27:33apis plan some time for the auth stuff
27:36because it's probably going to be the
27:37long poll in the tent right it's the
27:38hard thing to build but with that in
27:40mind it's the first thing that people
27:43have to use so the old joke goes if
27:45you're doing a two-day hackathon day one
27:47is off right no one builds anything in
27:49the first day they're just trying to get
27:51authenticated and get a token and make a
27:53call
27:54uh which is you know probably an
27:56indication of the level of quality
27:58sometimes that's out there but the other
28:00bit that I think is so easy to overlook
28:03in every place I've ever been it's like
28:05the thing I have to beat the drum on
28:07is if you can if you're trying to do
28:10that first step of auth you're trying to
28:12make that first call there's a pretty
28:14good chance your first experience with
28:15an API is going to be an error
28:18right uh and embracing that and saying
28:21that's okay we get that one you know you
28:23can do try it components and things like
28:25this to make it easier good code samples
28:27but prepare for the worst that folks are
28:31going to hit errors and make sure that
28:32you've got reference material you've got
28:35information on how to resolve those
28:37errors if it's a sort of 400 class thing
28:40that indicates it's you not us right
28:43um and so often you go in and try an API
28:46out you get an error that doesn't give
28:48you anything meaningful you might get
28:50internal stack traces and things that
28:52are just on the 200 I don't know what to
28:55do with this or a 200 that actually
28:57produces a stack Trace yeah that's the
28:59word like
29:01again I think when we take that example
29:04though and we look at let's document
29:07those things up front it also informs
29:09testing it also informs Security on if
29:13you didn't do that documentation up
29:15front how is anyone going to know how to
29:17plumb the depths of those things and
29:19quite often that's where like
29:20information leakage happens in security
29:22is you're exposing how your database is
29:26structured or how your internal uh you
29:28know call stack Works in ways that are
29:31not good that are giving someone a
29:33vector map of how to attack you well
29:35you've just hit on two other courses on
29:38on appisecu so appreciate the the
29:41alley-oop here one is
29:44um error disclosure right so like what
29:48are you revealing in
29:50um
29:51in your in your data right like when
29:54your results and your errors right and
29:55and the other
29:57um I lost my train of thought on the
29:59other one but I'm sure it'll come back
30:00to me but the the thing that's
30:02interesting from a security perspective
30:04on on Tessa you talk about like
30:06authentication right that's you know
30:09should be well defined it needs to be in
30:11your in your docs right so does
30:14authorization and then you got
30:16authorization right number one yeah or
30:19number two and number one on the oauth
30:21you know four years running right we
30:23should have like uh you know some sort
30:25of you know Banner or flag on that
30:28um and so yeah those are those are
30:31critical but what's what's maybe number
30:33three on the list is logic flaws and
30:37this is where like it's almost the
30:39opposite of what you test for in
30:42documentation
30:43um which is the documentation tells you
30:45what your API should do
30:47how it should behave how it's meant to
30:49behave right and of course what hackers
30:52will do is try to find the unexpected
30:55unintended ways that it shouldn't behave
30:58but does right and um to hammer that
31:01point home I'll I'll go to my sort of
31:04you know standard example
31:06um and I'm not pointing fingers but like
31:08at coinbase they they had a a really
31:11remarkable breach but and they responded
31:14to it brilliantly like I want to be real
31:16clear like fantastic response but what
31:18happened was somebody looked at the at
31:21the web app sniffed the traffic found
31:23the apis
31:25and then started manipulating them and
31:28in fact
31:29um what this person tried to do was was
31:31to send ridiculous requests in through
31:34the API specifically to get the error
31:37messages back looking for what info can
31:40I get from these error messages so one
31:43of the best practices don't reveal
31:45anything useful in your error messages
31:47right don't say that's an invalid user
31:50when everyone else it doesn't return
31:52that that user right or we're looking
31:54for an eight digit account code or
31:57whatever it might be and in this case
32:00um this ridiculous request turned out to
32:03actually get executed he changed his the
32:05asset he was selling ethereum to bitcoin
32:08by just changing what it was the
32:10description in the API call
32:13like having pesos and selling them as
32:15dollars right like no these aren't pesos
32:17these are dollars and it actually worked
32:19right so there probably wasn't anything
32:21in the the dock that said make sure that
32:26you you know the asset being sold is the
32:28thing that actually gets sold right so
32:30it goes to like yes you want to test the
32:33apis right and and do positive testing
32:36which is does it do what you specify but
32:39you can't consider yourself done uh at
32:42that point right like you've got to go
32:43do that more negative testing what's
32:46possible what's conceivable and just
32:48like you talk about using tools and and
32:51and technique or tools and and uh
32:54Technologies for creating your
32:55documentation same sort of things got to
32:58be done on your on your testing regime
33:01as well that's my little soapbox on on
33:04the need for testing here
33:07Alex go
33:10um you just triggered me a one I
33:12remember reading about an online shop
33:14that
33:15um as long as your car was a positive
33:17number you could check out so people
33:19were going in and like putting
33:20PlayStations and stuff in and they were
33:22doing it by sending the request set say
33:25add to basket and they were just
33:26changing the amount and as long as it
33:28was less than zero it was fine there was
33:31also stories of people checking out and
33:33getting paid because of it because in
33:35the body they haven't validated and said
33:37you know that basket total must be an
33:38integer must be greater than zero so
33:41these logic flaws are just sitting there
33:42so having a good API documentation and
33:45actually defining to say you know this
33:48is the schema these are the things these
33:50are the ranges that we're going to
33:51accept
33:53um stops people doing very bad stuff and
33:56you can even use like automation tools
33:58and code generation to say you know go
34:01and build me the validation Library
34:02that's going to sit in front of this API
34:04and you feed it the schema that you've
34:06written and it says yeah lovely somebody
34:08tries to send me a a request saying you
34:11know can I have five PlayStations for
34:13minus fifty dollars a piece please and
34:15it comes back and says sorry uh this
34:17can't be minus fifty dollars
34:19and that there's there's ways to
34:21automate that and save yourself some
34:23time well it's it's really critical I
34:25mean the examples are are too many and
34:28they're they're too prevalent um we all
34:30should be taking it real seriously as
34:32API owners and Developers
34:34and security teams um the logic flaws
34:38you know the the thing that's that's
34:40evident to me is we've relied on uis
34:44to be security enforcers right um uis
34:48control what data you see what buttons
34:50you can press you know it filters out
34:53the sensitive bits and all that
34:55um but really you know what an attacker
34:58will do is just go around the UI start
35:00using the apis behind the scenes and now
35:03all that protection goes out the window
35:04right like that coinbase attack could
35:07not have been executed through the UI
35:09it's impossible right there's no button
35:11to do that right and so for folks on on
35:15the call like that's another you know
35:16best practice like just you know make
35:20the UI be the presentation layer and
35:22that's it right if you're enforcing our
35:24servers dumb clients
35:26yeah right it's it's it's very
35:28convenient I get it right I'm not a
35:31coder but you know to be able to just
35:33you know like like the the case at venmo
35:35right there was an API powering the home
35:38page that would show you the most recent
35:39the most recent transactions and the UI
35:43would strip out all the sensitive bits
35:45right last name account number address
35:47whatever right turns out that API was
35:51calling that that homepage feature was
35:53calling an API that was calling the back
35:54end and the back end was returning every
35:57field of every record
35:59right and so great you just go to the
36:02API now you got all the data right so so
36:05you know another example but you know
36:07geez I pick like 10 slides to go through
36:09here Jason we're going to get to like
36:11one or two uh so maybe we'll just have
36:13you know a whole bunch more of these
36:15sessions but I gotta give you a chance
36:16to talk about this developer tries
36:18business guys that's a that's a
36:20recurring theme in the course and and
36:22what's behind that
36:23well first of all I have a
36:26it may be likable or an unlikable but
36:29it's a habit uh that I try to like sort
36:31of glum onto a phrase that reminds me of
36:33a big idea and this is one that for
36:36years is something that I've used in
36:38approaching documentation so
36:41it's really the idea that you know
36:44especially if you're trying to treat
36:45these things as a product it's kind of
36:47like you know Tangles your brain up
36:49trying to figure out I'm building this
36:51thing for Developers
36:53but developers don't ever buy anything
36:55somebody else is actually buying it
36:57right
36:58so when you start building developer
37:00products you understand this quickly if
37:03you want to survive is that you need to
37:06plea create a pleasing developer
37:07experience something that you know Alex
37:09I would have brought up the Keith quote
37:11if you didn't right like build something
37:13cool and go home on time right uh don't
37:16create toil don't make it hard
37:20um but at the end of the day like the
37:22developer themselves are turning to the
37:24folks with the budget and saying yeah
37:26this thing's good I'm happy with it go
37:28ahead and buy yeah they were Advocates
37:30only in places out there you go to
37:33persuade them first yeah so what where
37:36this really boils out in documentation
37:38is the first paragraph is not developer
37:42reference you are just describing what
37:44this thing does because there's another
37:47path in the door which is
37:50um you know a business operator product
37:53manager whomever that's non-technical
37:55you know say I'm scoping out how I'm
37:58going to compose this capability in our
38:00company maybe we should go buy versus
38:03build
38:05um and they're going to go look around
38:06for what's out there and if they look
38:08and the first thing they see is a bunch
38:10of technical gobbledygook they're gone
38:12and you're never going to win their
38:13business but instead if the first
38:15paragraph is you know
38:17this authorizes the credit card this
38:20completes the payment right something
38:22that anybody can understand this is what
38:25this is for you you've uh created a much
38:29more diverse set of opportunities to
38:31gain new business and gain adoption in
38:33the API now second paragraph and on sure
38:36you might go down in the weeds of how
38:38you call this thing and what the format
38:40of the data is coming back and all the
38:42stuff developers want to know but don't
38:44lead with that
38:46yeah
38:48um 100 let's see if we can get a couple
38:50more we've already talked about this
38:52plenty let's talk about creating
38:54documentation right like in fact
38:58um I'm gonna pop this question let's see
39:00if I can get this to work
39:02uh is that showing up on the screen
39:05here
39:07um
39:08and Yama uh Edwin says I've been using
39:11swagger to document my apis just
39:13thinking that's enough I put in an
39:14endpoint and a brief description right I
39:17think what we would say here is there's
39:19more to it right uh help us you know add
39:21some color here Jason and Alex to to
39:23this question or this comment
39:25yeah I mean I guess first we should call
39:27out that when people say Swagger we also
39:29mean open API it's a synonym uh
39:31Swagger's technically an old name but we
39:33all know it means the same thing and I
39:35would just say props for using open API
39:37uh right like having a description in a
39:41program in a you know contract
39:42programmatic fashion is a huge leg up I
39:47think
39:47you know uh taking a word doc or a PDF
39:51and just handwriting stuff without a con
39:55contractual programmatic tie-in is just
39:58a formula for disaster like as soon as
40:01it goes out the door you're going to
40:02have problems uh with keeping things up
40:04to date and keeping it accurate
40:09I guess echoing what you just said it's
40:12a little bit like we have Hoovers and
40:14Vacuums in in England over here and
40:16somebody said I'm going to Hoover and
40:17it's and then some
40:19um enthusiasts will say no no that's a
40:21brand you can't use that and it's a
40:22little bit like that so yeah open API is
40:24probably the more uh inclusive and open
40:26way of saying it but definitely that's
40:29kind of where we started with you know
40:31I've described my my resources so it's
40:35kind of been looking to say have you got
40:36all of your schemas defined are you
40:38starting to look at things where you
40:40might be able to drive some reuse so if
40:42you've got an example let's just say
40:43it's a catalog of products have you used
40:46the ability to define a product on its
40:50own as a schemer and then you've maybe
40:51got another schema that says this is
40:53what a list of products looks like and
40:55this is where your kind of open API
40:57reuse can really help accelerate and and
41:00drive that consistency forward we got to
41:03the point where we were trying to take
41:04away a lot of like the I'm gonna think
41:06the boring and uninteresting things so
41:08things like sorting impagnation we go to
41:11the point where there's only so many
41:12times somebody says how did you
41:13pagination here and if you haven't
41:15gotten documentation you know maybe they
41:17put it themselves just trying to find a
41:20pagination that you like and then write
41:21a schema for it that says this is how we
41:23paginate and then making sure that
41:26you're considering things like that
41:27awful lot of the the good best practice
41:30design decisions have a lot of parallels
41:33with governance and have a lot of
41:35parallels to security if you're
41:37designing an API and maybe you're not
41:38doing pagination today I'm going to come
41:40in I'm going to see how I can ask for
41:41can I ask for a million records is that
41:44going to start causing it into knowledge
41:45of service what if I start asking for a
41:47million records 100 times a second I've
41:50looked at your API you haven't got
41:51pagination you haven't got rate limiting
41:53so what if you change it around the
41:55other way and shifted left and we're
41:57using a tool that says when we review an
41:59open API as a design
42:01pagination on a list yeah what about
42:04something that Dan said which we would
42:06call information disclosure have you
42:08just done a copy of a whacking great big
42:11table and exposed everything including a
42:14password or something is that actually
42:16necessary talk me through that you can
42:19have these conversations because you've
42:20got this open API way of describing
42:23things have this conversation early nip
42:26them in the bud get them before they
42:27start growing the word I'd say probably
42:30that the worst thing about apis is if
42:32you put the functionality out there
42:34somebody will start using it for good or
42:36for bad and then when you turn around
42:38and say hey sorry we didn't need to
42:40expose that Sony puts around and said
42:42yeah but I need it yeah
42:44and then you become very unpopular very
42:46quickly as human beings somebody takes
42:48away a button or moves a button on the
42:50UI we kind of just kind of just cope
42:52with that if you take away a property
42:54change something on an API you could
42:56genuinely break somebody's Mission
42:58critical thing that they're relying on
43:00so with great power I can scrape
43:02responsibility there for sure but it's
43:04definitely on the right path now if
43:06anyone's doing anything with rest apis
43:07if you're not using open API you're
43:10missing out
43:11uh
43:18filling in the blanks so to speak in
43:20your open API or your Swagger and saying
43:23you know is that enough I I would
43:25certainly argue that
43:27if we're treating this as a product
43:28what's like job one the thing that that
43:31product manager should be great at is
43:33storytelling
43:34and I don't think that just filling in
43:38those blanks that's good reference
43:39materials think of that as you know
43:41that's the encyclopedia on the Shelf but
43:44that doesn't really tell the story of
43:47what this thing is good at what it's
43:49built for and I think the other bit that
43:53um you know when you see folks launch
43:54things that are too generically
43:56described
43:57sometimes you get serendipitous usage
43:59people sort of uh read that reference
44:03and they read it in a different way than
44:05you meant and they try to use it in a
44:06different way than you intended perhaps
44:09you thought people would call this once
44:11a day and talks this point they want to
44:13call it you know 20 times a second
44:16um if you didn't tell that story about
44:18the use case you had in mind to build it
44:19for or collection of use cases sometimes
44:23people will use it in ways that you did
44:24not expect that are not going to be a
44:26good experience for any of you yeah so I
44:28think it helps set those boundaries a
44:30little bit and guide it really attracts
44:33the right kind of folks looking to
44:35fulfill the right kinds of use cases
44:37with that additional sort of guide and
44:39task oriented content beyond the the
44:42encyclopedia the reference
44:45and some Jason like you know I want to
44:47wrap up here in the next few minutes but
44:49like
44:50I wanna you know untouched on here like
44:52generating documentation like let's talk
44:54for a sec on how to how what are these
44:57tools what are these techniques right
44:59because
45:00um and look you're at stoplight you guys
45:02have a technology that that helps people
45:05develop this there are linters I didn't
45:07even know what a linter was until I
45:09asked Alex to dumb it down for me
45:12um but help us understand like what do
45:14these tools do how do they help
45:17um and and even like what's out there
45:19yeah I mean I think the the starting
45:22point that a lot of folks find
45:24themselves at like I said before is like
45:26there's a Confluence article or a word
45:28doc or a PDF or whatever and like
45:30it's uh it's it's not accessible you're
45:34not gonna be able to really broadcast
45:35that out to a big audience
45:37um it's it's really easy to get out of
45:39sync out of date
45:41so now we start to try to solve the
45:43problem of let's tie this back in some
45:45way to the implementation that makes
45:47sense and I think there's really two
45:50schools of thought here and there's not
45:52really a wrong answer there's pros and
45:54cons to both I think the first and the
45:56most prevalent historically has been
45:58excuse me uh code first
46:01uh is what I'd call it is like you've
46:03coded an API and you put like
46:06annotations in the code that include the
46:09documentation in line with code or maybe
46:11references to markdown files or
46:14something and then you run a generator
46:16that takes all those annotations out of
46:18the code and sort of spits out the HTML
46:20for your documentation
46:22the advantage obviously is
46:25the the docs match the code right like
46:27it matches the contract
46:29um the downside is you let's say you
46:32decide to hire Tech writers and go
46:34document this thing
46:35now they have to go into GitHub they
46:37have to know how to navigate code so
46:40you're really limiting who can do that
46:42job into kind of the engineering Circle
46:44which
46:45for what it's worth like Engineers
46:47documenting their own apis is almost
46:49never a good outcome like it's they're
46:51too wrapped up in how to build it and
46:53not how to use it you need someone
46:55outside of that perspective we certainly
46:58take the more like design first approach
47:00the idea that
47:02um you know you sort of fill in those
47:03blanks in that open API that are already
47:05there telling you where to put
47:07descriptions
47:08um and then perhaps generate your code
47:11stubs from that same open API and this
47:14is the other really powerful concept is
47:16Swagger was originally built with
47:18generated documentation in mind but it's
47:21evolved over the last 10 years into
47:23being something that is really a
47:25universal contract to describe an API
47:28Beyond just the documentation in a
47:31programmatic fashion meaning that you
47:33can generate code you can integrate with
47:35all kinds of other tools so it opens up
47:38a whole ecosystem of things to connect
47:39to now
47:42there the the con is you could have a
47:45design that by the time it actually
47:47ships doesn't match so it is good to
47:50have some backstops kind of before you
47:52deploy that make sure that the
47:53implementation matches uh which but I
47:57mean if you're building apis this should
47:59be the best tested product you have uh
48:02so if you're not contract testing
48:04um I think it's a big mistake
48:07um couldn't agree more with that and I
48:09think you know let's let's rap god
48:12there's so much more we were we were
48:13hoping to get through here but
48:15um you know look all the more reason for
48:17folks to uh to try out your course
48:20um it's free it's uh it's right there on
48:22appisec University you don't need to
48:24type that whole URL just go to happy SEC
48:26University you'll see it there on the
48:28home page
48:29um you get to listen to Jason for about
48:31two hours it's self-paced so you don't
48:33have to do it all in one shot
48:35um it's an excellent course truly if
48:37you're if you're a security person if
48:38you're a developer if you're one of
48:40these newfangled API product managers
48:42that hopefully we'll see more of out
48:44there in the world
48:45um I think it's a great course for you
48:48and uh and and it is certified so you'll
48:51get a certification in the badge all
48:52that good stuff to to show
48:55um people what you've done
48:56um I'm gonna throw up the results of the
48:58poll here let's let's you know we threw
49:00that up at the at the beginning let's
49:01see what cry internally but try to sort
49:04it out there you go it's the can-do
49:06attitude
49:08um that seems um
49:11but Jason said it didn't he said
49:13developers try and and that's just us
49:15trying right that's what I said I was
49:17like I'll give it a go and uh I would
49:20Challenge and a couple of people I've
49:21met is if you see somebody's API that
49:23doesn't match the contract and that's
49:25the term that we would use just raise a
49:27GitHub issue and say oh by the way I was
49:29using your API and I noticed that you
49:31didn't have this documented or I got
49:32this different response they might
49:34genuinely not know and that could
49:36actually help those people to make a
49:38better API or a safer one so you know
49:41we're in a great world full of Open
49:43Source and people that are willing to
49:45help others I would say working in API
49:48has been the most inclusive and best
49:50people I've worked with
49:51um just across the group and just get
49:54involved yeah great Community for sure
49:59um last thing here um a little plug for
50:02our next webinar it's a few weeks out
50:04from now it's about PCI and DSs we have
50:07of course we just launched a week ago on
50:09uh API security for PCI compliance this
50:12is sort of interesting I mean if you if
50:15you're familiar with PCI it's all about
50:16credit card it's been payment uh
50:18protection
50:19um 4.0 has come out
50:22um you've got to comply sorry you've got
50:24to comply by next march
50:26to the 4.0 standards and guess what 3.0
50:30had no mention of apis zero I only know
50:33this because I did a control F and
50:35nothing showed up and uh in 4.0 it's
50:38it's all over uh it's all over it so if
50:41your organization has any PCI if you're
50:44doing payments you're touching credit
50:45cards you probably want to pay attention
50:47to this uh we've got a whole course on
50:50it and we'll be talking about what's in
50:52it and what do you need to know about it
50:54um big thank you to both of you guys
50:57um yeah definitely check out stop lights
50:59check out spectral we haven't even
51:01talked about spectral which is
51:02the open source linting tool that you
51:06can take advantage of um I know I know
51:08stoplight's got a number of other great
51:10tools out there and a great company
51:12really to work with and Alex thank you
51:14man
51:15um appreciate you always being ready and
51:17willing to share your expertise uh and I
51:20think it's uh it's been really fun to
51:21have you on the call and thanks everyone
51:23for joining um there are a lot of
51:25questions is this recorded yes uh it is
51:28and we'll be sending out YouTube links
51:30and all that good stuff later and
51:32um hope to see you all on the next one
51:34take care everybody
51:35foreign