Serialization Through Schema and ModelSchema Classes

00:00 In the previous lesson, I showed you how arguments are handled in Ninja. In this lesson, I’ll dive into serialization with Schema and ModelSchema classes.

00:11 So far, you’ve seen strings turned into JSON strings. Exciting it may be, but in the real world, you’re typically going to have to turn data into JSON objects.

00:21 This process is called serialization. Ninja is built on top of a serialization library called Pydantic. Pydantic uses the type annotation features of Python to describe objects, which it calls models.

00:37 This can be a bit confusing in the Django world, as Django already has something called a model. To get around this, Ninja renames Pydantic models as schemas. A Schema is a Python class used to describe some fields with type information.

00:54 This is very similar to Django ORM models. When an API needs to respond with some data, it uses a Schema to describe the payload.

01:07 To play with some data, I’ll need some data. So another lesson, another Django app. This time, I’ll be playing with dragon fire. The data in question will be a Person. The model for it is on the screen here.

01:20 It can also be found in the sample code if you want to just grab it. If you’re coding along with me, you’ll need to create a targaryen Django app, add the Person class in the models file, and of course, register all this stuff … so, add it to installed apps in your settings, register an API route, and of course, because you’re adding a model, you’ll need to do migrations as well.

01:42 Inside of my targaryen app, I’ve created schemas.py. Ninja doesn’t care where you create this, and if you’re only doing a little bit, sticking your schemas in models.py actually makes a little more sense. But for larger projects, you may want to organize your schemas together, like I’ve done here.

02:01 My first schema has nothing to do with the Person model. I’ll come back to those later. I’ve defined something called DragonOut.

02:08 This is a schema containing two fields: name and birth_year. The type annotations indicate what type of data will be in those two fields.

02:19 I named this DragonOut out of habit. Quite commonly in APIs, you’re going to need to have data coming in from a POST and going out from a GET.

02:29 Most of the time, this will be describing the same kind of object, but usually will contain different fields. Stuff going out has an ID field, whereas stuff you’re creating, something new, typically doesn’t have an ID field. One way of handling this is to use two different serialization classes, one for In and one for Out.

02:51 This is the pattern used in most of Ninja’s documentation, so I’ve stuck with it.

03:00 Inside of the targaryen API file, I’ve defined the dragons view. I tell the dragons view what I want to return by setting the response parameter in the GET decorator.

03:12 As this is going to return a list of DragonOut objects, the response type is set to list[DragonOut]. Inside of the view, I can create an instance of a DragonOut data object, or like I’ve done here, three of them.

03:27 I then return that list, and Ninja takes care the rest.

03:42 And taking a look at the curl output, you see the resulting JSON, a list with three serialized objects.

03:54 Since Ninja is a library for Django, the most likely thing you’re going to need to serialize is Django ORM models. As an ORM model already has type information inside of it, Ninja can do most of the work for you.

04:08 The ModelSchema class works a lot like a form object in Django. You inherit from the base class. Then in a subclass, you indicate what ORM model to serialize. In this case, I’m serializing the targaryen Person model.

04:24 The model_fields attribute indicates which of the fields from Person I’m going to include in the output. In addition to using fields from Person, you can also add new ones simply by declaring them.

04:37 I’ve declared the full_name attribute and then created a magical little method called .resolve_full_name(). Ninja automatically looks for static methods that start with resolve and will use them to populate a field. A resolve method takes an object as an argument, the thing being serialized, and then it returns the value of the field in question. Here, I’ve created full_name by combining the name and title of the Person object into a single string.

05:07 That’s why I didn’t include "name" or "title" in the model_fields list.

05:16 Now inside of the API endpoint, I declare that I’m returning a PersonOut as a response, then return a Person object. Ninja takes the Person ORM object, uses the PersonOut ModelSchema and serializes it all into JSON. Note that what I’ve done here isn’t the best coding practice.

05:37 If an ID is given that doesn’t correspond to a person, you’ll get a 500 error. Better practice is to kick out a 404, but I’ll show you that later. Let’s take a look at the call …

05:59 and there you go. One serialized Stormborn lady, which of course I had created in the database earlier using the admin.

06:10 If you want to take advantage of the serialization feature, but you’re not in a view, you can get at it directly from the ModelSchema object.

06:17 Let me show you an example copied from Django’s REPL. I got there by running the manage shell command, imported a Person, then import the corresponding schema.

06:28 Now I’ll query a Person from a previously loaded fixture, and then I use the .from_orm() method of the PersonOut object to turn my person into a data object. Here’s the result.

06:43 I can use the .dict() method to see the serialization as a Python dictionary or the .json() method to see it as a JSON string.

06:55 You’ve got all the pieces you need now to build a proper API. Next up, I’ll show you a typical CRUD use case where you create, read, update, and delete your data.