Detailed Notes
This video looks at one piece of our URL shortener solution. We have an API that we built and want to be able to provide documentation easily. We do this by embracing Swagger.
You can find out more through our online classes at https://school.develpreneur.com and register for free. Registration will add you to our email list and you will periodically receive coupons for courses as well as notifications of the latest releases.
Transcript Text
well hello and welcome back and we are continuing messing around with our shortener and we're specifically going to be doing some updates to our API and specifically we're going to cover a couple of things that we want to do which is basically answering the question how do I document my API and we're going to do a thing deal with a thing called Swagger which is a very useful tool as you're going to see fairly quickly we're going to do this into two parts because it's going to take a little bit because we're first going to have to actually tweak our code a little bit to make it more say Swagger friendly and then we're going to talk a little bit more about how we can make our stuff really look clean so now last summer round we had our API look roughly like this we've actually updated it on the delete but I'm just sort of going back to our essentially the problem here being that our format is we have this shorten and within that we basically just look at the request method and we say Okay within that how are we going to handle it so if it's a post we're going to go do that if it's a get we're going to do that when we switch over to Swagger it is going to want to what it's going to do is it's going to give us something that looks like this and actually let me blow this up a little bit so what we've got is it and it is documentation so if we click on this we're going to see here's what all of our endpoints are and we can actually click on it and we can see what it looks like we can actually even test it this is currently running so I can do try it out if I do a Hello and I execute it there's no parameters for it then it says okay so here's roughly what a curl would look like here's what the response over the request URL looks like boom here's what the response was and I can do it and play around with it but here everything is a Json response so we're just gonna that's what it's going to kick it back and it says hey here's a response code much like if we went over to our Postman and we just did a uh I believe this is hello we just call it hello then yep you're going to get the same thing get that back there so there you go so this documentation and I can clear it this allows us to very quickly as we're going to see document our API and make it useful for other people now in our case there's not a whole lot we need to do but as you get a more complicated API this becomes incredibly valuable it is very useful to have a way to go in in particular things like this so I could go in and I can actually run a query and try it out and see what it looks like without having to set up Postman without having to set up all of this other stuff as long as the API is out there running I can test it and I can test it live as it is this is automatically updating documentation and if you say wow that's awesome well that's what we're going to talk about that's what we're going to do it so the first thing I want to mention is that when we first did this with the apis we took this approach we are going to actually change it and it's not that we're going to change it a lot so this is what we had and what we're going to do is we're going to change it over to this and we're going to use some decorators because this is going to now become very important for how we call our make our API calls we had them before but we're going to tweak them just the slightest bit and we're going to be able to add some documentation so that's our first step and all we have to do is each of these IFS is going to become a function with that name so for example here since we have very simple stuff all we have to do is we're going to take this post we're going to create a function called post we're going to have resource that's going to be sent to it and they're going to return the Json of the result so as you can see here before we were saying if the method's post which is going to come in here shorten is our class and this is our endpoint and it's got methods of get post and delete so we've got for example post we're going to come in and all we're going to do is going to retrieve the New York URL based off the form jsonify the result convert that to Json and return it which is almost exactly what we did before and we're going to do that for each of our methods I'm not going to and what we did here if you remember you know we'd come through and everything we called it and then we jsonify it but now it's we're going to just do that at each level so it's just the slightest bit of code change for us to do this that gives us now that we've got a class for basically each endpoint and then we've got so we've got our heartbeat which is hello and this is our route and then we've got within it we we don't actually say anything we're going to assume to get but we could just easily do it this way and say that it has a get a post and a delete and if you look at our documentation by default it has a get if we change it to specifically state that it has a get and we come back and run it then yeah we see the same thing now if we wanted to do a uh let's do a delete let's see is here if we do a delete and return let's say sorry delete is not available and we reset it then we're gonna see here delete is now available notice they're actually color coded we could go in here we could try it out execute it delete is not available there you go and we can even you know there's a bunch of stuff we can do with this but the key here is that we get to do our um where I want to oh I'll roll that back up I want to do is be able to see our endpoints and our documentation and it's as you can see fairly full featured it's like okay what are the parameters what are the responses now you'll note we have as we've seen before there's like a default there's no problem parameters and you have a code of 200. now there may be other ones that it returns but we'll talk about that in essentially in part two I want to do is just get us started on this for this part now the thing that we need to do before is we had flask and we had jsonify and we had requests and we were using shortener and flask CRS I believe we talked about that and it was basically just to avoid uh cross-site issues what we're going to do is we're going to bring in this thing called flask rest X and all you have to do to bring it in is do a pip 3 install flask underscore rest x r e s t x and when you do that boom you're going to be able to do it go run through your stuff it'll install and you're going to want resource which is this thing that we see here you're going to want API now before we used app equals flash name just gets us going it's like boom we've got our API remember flask is super easy so we use app and we're off and running however what we're going to do for the documentation side of it is we're going to create this new thing called API and we're going to use the flashed risk the flask rest X very difficult to say quickly API and we're going to use app we're going to stuff it in there so we're basically just going to wrap around our app this API stuff and we're still going to do the cores on the app not the API API itself now you can do uh the most basic version is if you just wrap it you're going to get a bunch of default stuff so I'm going to come in here if I go look at my documentation then it's just API it assumes version 1.0 there you go I know there's some things that we can add here which is what I did so here I add that hey this is going to be version 1.0 the title is a shorty API and a description I'm going to say like okay I'll change a little bit but here are the calls and examples for the shorty API dplink.us for more information so we can do that and when we do that let's see so we'll go look at what that looks like and now what we're going to see is now our title is shorty API instead of just API we have a base URL we have a version that we did and then we've got this little documentation section now we can get pretty complex with this um I believe we can do let's do this um I'll just do this just because but we're going to look a little bit more at some of the tags and stuff that you can do so if I do this I think I can do straight up HTML and if we do so there we go so I've got author I've got this is HTML text so I can actually get pretty impressive with that base URL I believe is just base URL so I could say if for reasons it's something else let's just say it was last it was Slash shorty I think that'll work I'm playing around with this a little bit but as you whoops as you can see oh that wasn't it okay however we're not going to mess with that we'll come back with a little bit some more ways that we can do it but it's basically we can like do some fairly you know complicated stuff here I wonder if author apologies as I'm thinking through this but there's a lot of little things in here as you see with most Auto documenting things oh okay uh oh I forgot my comma if I go here yeah this author doesn't give me anything but there's probably some tags in there if I go look at the Swagger API then I can look at there's going to be other tags that I can do to that if you want to look to swagger.json this tells you basically everything that's come through so this is how it generated this Swagger dock so you could actually generate something you know you could make some changes and do some funky stuff if you want to that's not something we're going to talk about right now so documentation wise you can now see what it is that all these endpoints are and we can actually get into some of the specifics Now by default we notice that there aren't any parameters so I do so we can get something useful I want to get you tell you how I got to this one because I'm going to do that actually through all of these so this is uh the get and notice here it's like here it says hey this is a short URL you want to decode and it's a string that it's looking for and if I try it out I can enter a URL yeah let me go enter a URL that makes sense um I think six will give me something yeah so if I use this as my URL I'll come back over here I kick that in then I'm going to see right here uh here we go here's my output so code was 200 there you go if I do something it doesn't like um let's see if I do this I think it'll blow it up yeah so if I take this I'm also going to see if I go here V execute then I see data negative one error so I'm gonna get I can actually play around with this like I said just like if I'm sitting in Postman I can make the calls and actually get something you know fairly useful out of it so I can do a lot of testing before I even set up anything else I can do it right in here with swagger and notice that basically all I'm doing is that all I did is I just basically have my routes now the exceptions are we went ahead here and we created methods for each of them and so we did two you know we did it a little bit differently but not much and now here is where so we've got this at API dock so I can do this pretty much anywhere that I want to so what I could do is I could say that I'm sending a URL for each of these but I'm not going to because I'm going to well actually let's do it that way so if I want to cheat I can do this and now this is going to be up at that level let's take a look at what this looks like so when I do it up at the class level so each of the shortens now have URL as the as a parameter so if I try it out with post there we go okay so if I want to do a HTTP colon my cool URL .com and I execute it and in this case it's because my it's a post as opposed to just a regular parameter so it's actually going to blow up because it didn't come up as a form so what I really want to do is I want to take this down and I'm going to do it on the get post but now here I'm going to need a form URL that I'm going to have to deal with in order to actually post it properly because here uh let's see yeah see it just it did it as a parameter as opposed to a a form parameter a form param so we're going to talk about that next time around let me get a little deeper into it but right now what we've got is something that we've really changed almost nothing and we have some pretty good you know documentation that we can do here now we can also do some other stuff like uh here uh API dock there's a lot that we can do here but we could basically say um and I've got to remember what it is but let's just do well let's just do like a straight up which is a test Bit O documentation I think it has to have a name I don't think it does it as a straight up string I don't think it's going to like that we're going to find out if we come back yeah so it's not going to give us anything terribly useful we just didn't it doesn't know where to assign it so we're going to step into this a little bit more next time around I want to give us just a basic so right now you could sit here and create a pretty solid document next time around we're going to add some more things show you where to look to add your own features because a lot of this as you've seen is pretty full featured it's just a matter of knowing what those features are so we will get back to you next time thanks a lot for your time if you have any questions send it out to email at info developmentor.com you can see some links around this YouTube site as well as some of the other places check out school.developreneur.com if you want to get a little more involved in some of this kind of stuff and uh definitely let us know what your you know some of the maybe the apis that you're building and some of your little documentation things that you've figured out and uh stick around next episode we're going to get a little deeper into it have yourself a great day we will talk to you next time [Music] thank you
Transcript Segments
well hello and welcome back and we are
continuing messing around with our
shortener and we're specifically going
to be doing some updates to our API and
specifically we're going to cover a
couple of things that we want to do
which is basically answering the
question how do I document my API and
we're going to do a thing deal with a
thing called Swagger which is
a very useful tool as you're going to
see fairly quickly we're going to do
this into two parts because it's going
to take a little bit because we're first
going to have to actually tweak our code
a little bit to make it more say Swagger
friendly and then we're going to talk a
little bit more about how we can make
our stuff really look clean
so now last summer round we had our API
look roughly like this we've actually
updated it on the delete but I'm just
sort of going back to our essentially
the problem here being that our format
is we have this shorten and within that
we basically just look at the request
method and we say Okay within that how
are we going to handle it so if it's a
post we're going to go do that if it's a
get we're going to do that
when we switch over to Swagger it is
going to want to what it's going to do
is it's going to give us something
that looks like this and actually let me
blow this up a little bit
so what we've got is it and it is
documentation so if we click on this
we're going to see here's what all of
our endpoints are and we can actually
click on it and we can see
what it looks like we can actually even
test it this is currently running so I
can do try it out if I do a Hello and I
execute it there's no parameters for it
then it says okay so here's roughly what
a curl would look like
here's what the response over the
request URL looks like boom here's what
the response was
and I can do it and play around with it
but here everything is a Json response
so we're just gonna that's what it's
going to kick it back and it says hey
here's a response code much like if we
went over to our Postman and we just did
a uh I believe this is
hello we just call it hello
then yep you're going to get the same
thing
get that back there so there you go
so
this documentation and I can clear it
this allows us to very quickly as we're
going to see document our API and make
it useful for other people
now in our case there's not a whole lot
we need to do but as you get a more
complicated API this becomes incredibly
valuable
it is very useful to have a way to go in
in particular things like this so I
could go in and I can actually run a
query
and try it out and see what it looks
like without having to set up Postman
without having to set up all of this
other stuff as long as the API is out
there running I can test it and I can
test it live as it is this is
automatically updating documentation and
if you say wow that's awesome well
that's what we're going to talk about
that's what we're going to do it so
the first thing I want to mention is
that when we first did this with the
apis we took this approach we are going
to actually change it and it's not that
we're going to change it a lot
so this is what we had
and what we're going to do is we're
going to change it over to this and
we're going to use some decorators
because this is going to now become very
important for how we call our make our
API calls we had them before but we're
going to tweak them just the slightest
bit
and we're going to be able to add some
documentation
so that's our first step and all we have
to do is each of these IFS
is going to become a function with that
name
so for example here since we have very
simple stuff all we have to do is we're
going to take this post we're going to
create a function called post
we're going to have resource that's
going to be sent to it
and they're going to return the Json of
the result so as you can see here before
we were saying if the method's post
which is going to come in here shorten
is our class and this is our endpoint
and it's got methods of get post and
delete so we've got for example post
we're going to come in and all we're
going to do is going to retrieve the New
York URL based off the form jsonify the
result convert that to Json and return
it which is almost exactly what we did
before
and we're going to do that for each of
our methods I'm not going to
and what we did here if you remember you
know we'd come through and everything we
called it and then we jsonify it but now
it's we're going to just do that at each
level so it's just the slightest bit of
code change for us to do this
that gives us now that we've got a class
for basically each endpoint and then
we've got so we've got our heartbeat
which is hello and this is our route and
then we've got within it we we don't
actually say anything we're going to
assume to get but we could
just easily
do it this way and say that it has a get
a post and a delete
and if you look at our documentation by
default it has a get
if we change it to specifically state
that it has a get
and we come back and run it
then yeah we see the same thing
now if we wanted to do a uh let's do a
delete
let's see is here if we do a delete
and return
let's say sorry
delete is not available
and we reset it
then we're gonna see here
delete is now available notice they're
actually color coded we could go in here
we could try it out execute it
delete is not available there you go and
we can even you know there's a bunch of
stuff we can do with this but the key
here is that we get to do our
um where I want to oh I'll roll that
back up
I want to do is be able to see our
endpoints and our documentation and it's
as you can see fairly full featured it's
like okay what are the parameters what
are the responses now you'll note
we have as we've seen before there's
like a default there's no problem
parameters and you have a code of 200.
now there may be other ones that it
returns but we'll talk about that in
essentially in part two
I want to do is just get us started on
this for this part
now the thing that we need to do before
is we had flask
and we had jsonify and we had requests
and we were using shortener and flask
CRS I believe we talked about that and
it was basically just to avoid uh
cross-site issues what we're going to do
is we're going to bring in this thing
called flask rest X and all you have to
do to bring it in is do a pip 3 install
flask underscore rest x r e s t x and
when you do that boom you're going to be
able to do it
go run through your stuff it'll install
and you're going to want resource which
is this thing that we see here you're
going to want API
now before
we used app equals flash name just gets
us going it's like boom we've got our
API remember flask is super easy so we
use app and we're off and running
however
what we're going to do for the
documentation side of it is we're going
to create this new thing called API and
we're going to use the flashed risk the
flask rest X very difficult to say
quickly API and we're going to use app
we're going to stuff it in there so
we're basically just going to wrap
around
our app this API stuff
and we're still going to do the cores on
the app not the API API itself now you
can do
uh the most basic version
is if you just wrap it you're going to
get
a bunch of default stuff
so I'm going to come in here if I go
look at my documentation then it's just
API it assumes version 1.0
there you go
I know there's some things that we can
add here which is what I did so here I
add that hey this is going to be version
1.0
the title is a shorty API and a
description I'm going to say like okay
I'll change a little bit but here are
the
calls and examples for the shorty API
dplink.us
for more information
so we can do that
and when we do that let's see so we'll
go look at what that looks like
and now what we're going to see is now
our title is shorty API instead of just
API we have a base URL we have a version
that we did and then we've got this
little documentation section now we can
get pretty complex with this
um I believe we can do let's do this
um I'll just do this
just because
but we're going to look a little bit
more at some of the tags and stuff that
you can do so if I do this I think I can
do straight up HTML
and if we do so
there we go so I've got author I've got
this is HTML text so I can actually get
pretty impressive with that base URL
I believe is just base URL
so I could say if for reasons it's
something else
let's just say it was last it was Slash
shorty
I think that'll work
I'm playing around with this a little
bit but as you whoops as you can see
oh that wasn't it okay
however we're not going to mess with
that we'll come back with a little bit
some more ways that we can do it but
it's basically we can like do some
fairly you know complicated stuff here I
wonder if author
apologies as I'm thinking through this
but there's a lot of little things in
here as you see with most Auto
documenting things
oh okay
uh oh I forgot my comma
if I go here
yeah this author doesn't give me
anything but there's probably some tags
in there if I go look at the
Swagger API then I can look at there's
going to be other tags that I can do to
that
if you want to look to swagger.json this
tells you
basically everything that's come through
so this is how it generated
this Swagger dock so you could actually
generate something you know you could
make some changes and do some funky
stuff if you want to that's not
something we're going to talk about
right now so
documentation wise you can now see
what it is that all these endpoints are
and we can actually get into some of the
specifics Now by default
we notice that there aren't any
parameters so I do
so we can get something useful I want to
get you tell you how I got to this one
because I'm going to do that actually
through all of these so this is uh the
get
and notice here it's like here it says
hey this is a short URL you want to
decode and it's a string
that it's looking for and if I try it
out
I can enter a URL
yeah
let me go enter a URL that makes sense
um
I think six will give me
something yeah
so if I use this as my URL
I'll come back over here I kick that in
then I'm going to see right here
uh here we go here's my output
so code was 200 there you go if I do
something it doesn't like
um let's see if I do this I think it'll
blow it up yeah
so if I take
this
I'm also going to see if I go here V
execute then I see data
negative one error so I'm gonna get I
can actually play around with this like
I said just like if I'm sitting in
Postman
I can make the calls and actually get
something you know fairly useful out of
it so I can do a lot of testing before I
even set up anything else I can do it
right in here with swagger and notice
that
basically all I'm doing is that all I
did is I just basically have my routes
now the exceptions are
we went ahead here and we created
methods for each of them and so we did
two you know we did it a little bit
differently but not much
and now here is where so we've got this
at API dock so I can do this pretty much
anywhere that I want to
so what I could do is I could say that
I'm sending a URL for each of these but
I'm not going to because I'm going to
well actually let's do it that way
so if I want to cheat
I can do this and now this is going to
be up at that level
let's take a look at what this looks
like
so when I do it up at the class level
so each of the shortens now
have URL
as the
as a parameter so if I try it out
with post
there we go okay so if I want to do a
HTTP colon
my cool URL
.com and I execute it
and in this case it's because my it's a
post as opposed to just a regular
parameter so it's actually going to blow
up because it didn't come up as a form
so what I really want to do is I want to
take this down
and I'm going to do it on the get
post
but now here I'm going to need a form
URL
that I'm going to have to deal with in
order to actually post it properly
because here
uh let's see yeah see it just it did it
as a parameter as opposed to a a form
parameter a form param so we're going to
talk about that next time around let me
get a little deeper into it but right
now what we've got is something that
we've really changed almost nothing and
we have some pretty good you know
documentation that we can do here now we
can also do some other stuff like uh
here
uh API dock
there's a lot that we can do here but we
could basically say
um
and I've got to remember what it is but
let's just do well let's just do like a
straight up
which is a test
Bit O
documentation I think it has to have a
name I don't think it does it as a
straight up string I don't think it's
going to like that we're going to find
out
if we come back
yeah so it's not going to give us
anything terribly useful we just didn't
it doesn't know where to assign it
so we're going to step into this a
little bit more next time around I want
to give us just a basic so right now you
could sit here and
create a pretty solid document
next time around we're going to add some
more things show you where to look to
add your own features because a lot of
this as you've seen is pretty full
featured it's just a matter of knowing
what those features are so we will get
back to you next time thanks a lot for
your time if you have any questions send
it out to email at info
developmentor.com you can see some links
around this YouTube site as well as some
of the other places check out
school.developreneur.com if you want to
get a little more involved in some of
this kind of stuff and uh definitely let
us know what your you know some of the
maybe the apis that you're building and
some of your little documentation things
that you've figured out and uh stick
around next episode we're going to get a
little deeper into it have yourself a
great day we will talk to you next time
[Music]
thank you