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.

Talk Python's Mastodon Michael Kennedy's Mastodon