Demonstrating and Swaggering

00:00 In the previous lesson, I showed you code for create, update, and delete operations in your app. In this lesson, I’ll demo FastAPI’s built-in web interface to interact with your API.

00:12 There are standards out there on how to document an API, and to go along with that, there are tools for interacting with them that follow that standard on the web.

00:21 One of the more popular ones is known as Swagger UI, and it’s built into FastAPI. To use the interface, visit the /docs URL on your FastAPI with your browser.

00:33 The web interface shows each of your API’s endpoints, documents the supported arguments for them, and provides a mechanism for making calls to the API through the web.

00:42 It also shows you an example curl call you could use to perform the same function on the command line. There’s an alternative to Swagger called /redoc. FastAPI supports it as well, just under a different URL.

00:55 Both of these features are on by default, but you can turn them off by passing configuration options to the FastAPI object in your main.py file.

01:04 Having the documentation makes it easier for your users to discover how the API works. It also tells nefarious types exactly what calls are defined on your system.

01:13 That said, hiding your calls might slow somebody down a little, but it isn’t really security. The choice to turn off the interface is there if you want it.

01:22 I’m still running our digital library API in the background, so now I’m going to open a browser and show you Swagger UI. Let me type in the URL,

01:36 and this is the interface. I’m going to start by scrolling down to the bottom here. This is the documentation for the data in the app. You can see the Book and NewBook classes as well as the kinds of errors the system can generate.

01:51 Let me expand the Book class.

01:54 It shows you the fields for the class, each of their types, and the little red star means that they’re required. Let me scroll back up. Each one of our API endpoints is listed here along with the HTTP methods that go with it.

02:08 If I expand the GET mechanism, at the top here, it shows you the argument that you need to call it, and if I scroll down, you can see what it expects to return.

02:20 Remember, serialized JSON is just a string, hence the simplicity of the return value.

02:27 You might have noticed the ‘Try it out’ button. If I click it, I can fill in the book ID and press Execute.

02:39 In the response section, I get a few different things. It shows the equivalent curl call I could use in case I wanted to do this on the command line, and then shows the URL that got used. Down below, it shows the response that came back. Pretty neat, huh?

02:56 You’ve got full use of your API through a handy web-based GUI. Now let me show you the create step as well.

03:07 Same idea here. Let’s try it out.

03:11 And you get an editor with a prefilled example of a data body. All I have to do is replace the example.

03:30 And there you go. A scary bat to go with our scary clown and our scary fish. Huh? I just realized, Dune sort of broke that pattern. Scary dirt? Scary worm, there you go. Scary worm.

03:46 Having a web interface to your API is quite handy, not just for testing, but also so your users know how to call your app. The last lesson is next. There, I’ll summarize the course and point you at some more content.