Should I duplicate or inherit a python dataclass which changes attributes based on the version of an API endpoint?

Question

I'm working on a python library for a REST API.I'm using python data classes to represent the structure of the returned JSON

The v2 of this API returns a slightly different object when compared to v1. Here's an example:

v1

{
    "animal": {
        "breed": "retreiver",
        "color": "brown",
        "name": "spot"
    }
}

v2

{
    "animal": {
        "genus": "retreiver",
        "color": "brown",
        "name": "spot"
    }
}

^{Biologists, please don't flame me. This is just an example}

What is the right way to create a data class for this?

1. Create a data class with just the common attributes between v1 and v2. Then create an inheriting subclass with the different variables for v1 and v2 separately. This subclass is what is used used to represent the API response.

2. Maintain a separate class for each version. Even though there's some repetition, the responses aren't going to change for a version. So you don't have to modify the data class in the future anyways.

Are there any downsides with these options I haven't considered?

Answer 1

Once I got around to finding out how to do this with Pydantic, I found it is exceedingly easy, at least as long as you are dealing with such a small difference between the two structures. You'll need to install pydantic to try the following working example:

from pydantic import BaseModel, Field


class Animal(BaseModel):
    genus: str = Field(alias="breed")
    color: str
    name: str

    class Config:
        allow_population_by_field_name = True


spot = Animal(genus="retriever", color="brown", name="spot")

json_v1 = spot.json(by_alias=True)
json_v2 = spot.json()

print("v1 out:", json_v1)
print("v2 out:", json_v2)

animal_v1 = Animal.parse_raw(json_v1)
animal_v2 = Animal.parse_raw(json_v2)

print("v1 in:", animal_v1)
print("v2 in:", animal_v2)

Output:

v1 out: {"breed": "retriever", "color": "brown", "name": "spot"}
v2 out: {"genus": "retriever", "color": "brown", "name": "spot"}
v1 in: genus='retriever' color='brown' name='spot'
v2 in: genus='retriever' color='brown' name='spot'

If you aren't familiar with Pydantic, it builds upon dataclasses to add a lot of really useful features. Every time I dig into it, I find more interesting things. I even used it recently to help me generate an antiquated wire format that you can't get libraries for, at least not for free. I've wrestled with serialization for decades and it's a really good tool. Other really good frameworks like FastAPI are built upon it as well.

Answer 2

2 is by far the simplest. However, that just perpetuates the problem.

How is this used? If it's possible to get to a point where you can use this without knowing which version it is then that's work worth doing. Any work you do along the lines of 1 should be aimed at that goal. What you build shouldn't just emerge from looking at the data. Consider what's going to be done with this.

You said the responses aren't going to change. Which makes me think these are immutable. So we don't have to worry about saving updates. In that case I'd lean towards your own data class that can only be populated with what you need. Write methods to populate it from either version. Now you can call things what you want to call them.