RESTful and HTTP APIs in Pyramid Transcripts
Chapter: Documenting your API
Lecture: Documentation options
Login or
purchase this course
to watch this video and the rest of the course contents.
0:01
In this short chapter we're going to wrap up the course by looking at your options for documenting your apis.
0:08
If you have a public api, you really should be documenting it, if it's internal, maybe, we'll see.
0:14
So, let's take a look at some of these considerations. First of all, how are we going to go about creating these docs,
0:19
do we need them at all— maybe, like I said, if it's a public api you absolutely need to have good docs,
0:25
if it's an internal api and you work at a company with a couple of developers, maybe just the unittest and an example app is good enough,
0:34
you don't really need to overly document it. If you work within a large company or you do an open source, you definitely need to document it as well.
0:41
Okay, so let's suppose you've decided, yes, I do want documentation for my api, one option is to just host them on read the docs,
0:48
so you go over there, create an account, set that up, that's an option; you could host them on github, and by that I mean you just have a repository
0:55
that is a bunch of read me files, or you know mark down files that people can browse through. An example of this would be basecamp,
1:02
at the beginning of this course we saw that basecamp has all of their documentation just as markdown files
1:08
maybe restructured text, one of those two on github, so that's certainly an option. You could generate them from a static site generator type thing
1:16
and then just put them up on a web server somewhere, that would be fine; so all these things here,
1:21
all of these options kind of leave you to your own devices, if you want to go this path they're pretty well documented there.
1:26
But in this section, I want to show you how to actually add the documentation to where your api is executing, inside the pyramid web app.
1:35
So we could host them right in this application here, or something along those lines okay,
1:41
so you can read the docs about working with read the docs, and things like that,
1:44
but if you want to host them within your app and kind of keep it all bundled together
1:47
then we'll see how to do that, it turns out to be super, super easy. So we'll add our documentation and we'll have a couple of pages
1:55
we should probably feature it pretty clearly, put a little nice design on it, things like that,
1:59
so here's the page that we might click on, see docs/all_autos and this might tell you how to get all of the automobiles from our service, right.
2:07
We saw, as you know, we've been doing this for a while now get/api/autos, and that's going to return a json response of this type,
2:14
actually it's going to return, the screenshot might be a little off, it is going to return a list of those, right so here is the general response,
2:23
and I think the style, there's not much to it, but also having it look pretty definitely makes it feel more polished
2:27
and people are more likely to use this api if the documentation looks at least somewhat professional, right.
2:32
Now, we'll have another one of these for when we're going to create a car so here we are going to post the api/autos the submitted body is this,
2:39
the response options are json and csv and they come out like this on the bottom. All right, so let's see how we add this to our auto service.