Improve route handler parameter support for Form request data

[sschaub]

Currently, Starlite supports validating submitted form data by defining a model class, like this:

@dataclass
class User:
    id: int
    name: str


@post(path="/")
async def create_user(
    data: User = Body(media_type=RequestEncodingType.URL_ENCODED),
) -> User:
    return data

In some cases, it would be convenient to receive form data via multiple route handler parameters. Other API frameworks such as hug and FastAPI allow this. Here's how that might look:

@post(path="/")
async def create_user( id: int = Form(), name: str = Form() ) -> ...:
    ...

The Form() function would have a design similar to the existing Parameter() function, providing pydantic options for validation.

Thanks for considering this!

[provinzkraut]

In some cases, it would be convenient to receive form data via multiple route handler parameters

Could you provide an example where this is more convenient?

The way it's currently implemented is a design choice. Having multiple instances of Form for one request body doesn't make a lot of sense semantically, since a request only has one body, therefore should only be able to have one Form. The example you gave would only make sense if it was FormField, since that's what it actually is.

Starlite expects you to define the schema of the request body as is; It's one schema for one form. It's not any different than receiving a JSON body: You also wouldn't declare individual fields of it as independent parameters. It's one JSON object, and should be reflected as such.

[sschaub]

Your point about the semantic issue with the concept of Form is well taken. I modeled my example after FastAPI's approach:

https://fastapi.tiangolo.com/tutorial/request-forms/

Perhaps using the term FormField instead of Form would be a better semantic match for what is intended. Does this make better sense?

@post(path="/")
async def create_user( id: int = FormField(), name: str = FormField() ) -> ...:
    ...

Regarding an example where this proposal would help:

There are times when API endpoints are used to perform some non-idempotent action that does not map neatly to a model-oriented REST POST/PUT/PATCH/DELETE scenario. Examples might include sending an email, performing a logout, etc. Often the POST verb is used in these cases. The request parameters for those endpoints do not represent the attributes of a model, so it doesn't make sense to require the API to define a model class in order to specify the parameters. Such model classes are used only once - to specify the parameters for the endpoint. Allowing the endpoint to specify FormField parameters directly instead of having them specified in a separate class will increase the writability of the framework.

As I was reflecting on this proposal, I realized that I should not have focused the proposal on form-encoded data. The scenarios apply whether the request data is encoded using x-www-form-urlencoded, JSON, or something else. So allow me to broaden the proposal. The scenarios I have in mind would benefit generally from Starlite route handlers that can specify multiple parameters that are populated with request body data. FormField could be used for data encoded in x-www-form-urlencoded format, and BodyParameter could be used for data encoded in JSON format. Naturally, a given route handler could use one or the other type of specification, but not both, since a request body has to be encoded one way or the other. FastAPI allows this, and uses the terms Form and Body, respectively, for these cases.

As an alternative to introducing both FormField and BodyParameter, perhaps the route handler decorator could specify the expected encoding for body data, and BodyParameter could be used for all of the body parameters to be received:

@post(path="/", body_media_type=RequestEncodingType.URL_ENCODED)
async def send_email( to_addr: str = BodyParameter(), subject: str = BodyParameter(), msg_text: str = BodyParameter() ) -> ...:
    ...

[provinzkraut]

The request parameters for those endpoints do not represent the attributes of a model, so it doesn't make sense to require the API to define a model class in order to specify the parameters.

I think this is where you're misguided. They do represent attributes of a model. The model is that of the request body. Each request can only have one body. Starlite enforces that you reflect this by also only allowing you to define it in such a way.

Aside from that, I think the costs far outweigh the benefits here, since the only thing it allows you to do is access form fields with one less attribute lookup.

since a request body has to be encoded one way or the other.

This is an important point and, evidently, Starlite's way is more Pythonic and explicit. FastAPI under the hood will create a single model for the request body, validate it, split it up and pass it into your function as separate parameters. Starlite on the other hand make this single model explicit.

[sschaub]

The request parameters for those endpoints do not represent the attributes of a model, so it doesn't make sense to require the API to define a model class in order to specify the parameters.

I think this is where you're misguided. They do represent attributes of a model. The model is that of the request body. Each request can only have one body. Starlite enforces that you reflect this by also only allowing you to define it in such a way.

By this logic, wouldn't the query parameters represent a model as well? Each request can have only one set of query parameters. Why doesn't Starlite enforce that by requiring a model be specified for the query parameters?

Aside from that, I think the costs far outweigh the benefits here, since the only thing it allows you to do is access form fields with one less attribute lookup.

The writability benefits seem clear. What are the costs?

[Goldziher]

at least in part this is going to make openapi spec generation harder. Its also arguable whether there is a benefit in this style of writing parameters. I tend to agree with @provinzkraut that this is not a good addition.

[provinzkraut]

Each request can have only one set of query parameters.

That's true. I was just responding to your idea that the model for a request body wouldn't represent an actual thing.

The writability benefits seem clear. What are the costs?

The benefits are subjective. I said they're outweighed because they wouldn't allow you to achieve anything you can't right now. But the downsides are:

• As @Goldziher said, it's going to introduce additional complexity
• It's going to break with the "one clear way to do things" philosophy (i.e. "You receive the validated and request body via the data parameter)
• It encourages bad practices (i.e. not modelling your data strictly where you should, having varying schemas for things that should be unified etc.)

As for the upsides, even those are questionable. Compare:

@post(path="/", body_media_type=RequestEncodingType.URL_ENCODED)
async def send_email(to_addr: str = BodyParameter(), subject: str = BodyParameter(), msg_text: str = BodyParameter() ) -> ...:
    ...

class Form:
    to_addr: str
    subject: str
    msg_text: str


@post(path="/", body_media_type=RequestEncodingType.URL_ENCODED)
async def send_email(data: Form) -> ...:
    ...

I wouldn't say that the first one is any easier to write, read, more succinct or clear. The only thing it is is less explicit.

Starlite is a self-described opinionated framework. This means that sometimes, you're not going to agree with the way Starlite does things, but it's an explicit non-goal for Starlite to support everyone's way of doing things. If there's something that can't be done we'll probably consider adding that, but this is mainly a case of wanting to do something that's already possible in a different style.

[sschaub]

Thank you @Goldziher for mentioning a cost.

I wouldn't say that the first one is any easier to write, read, more succinct or clear.

One important readability advantage of the proposed approach is the principle of locality: specifying the parameters in the request endpoint function signature means that the person reading the function doesn't have to hunt for the definition of a model class to determine the specification of the parameters.

Regarding writability: in your example above, the Form model class looks very clean because it contains only data type specifications. Because my example has to repeat the BodyParameter() notation for each parameter, I can understand why it doesn't appear to have a writability advantage. But if the parameters had additional specifications other than just the data type, the specifications for writing either route parameters or model class fields would be similar, and I think the writability advantage would be on the side of the proposal.

I also am having difficulty following the logic that the proposal encourages bad practices, given the inconsistency between Starlite's approach to query parameters vs. body data. However, your point about the "one clear way to do things" philosophy is compelling.

I do appreciate the consideration you are giving to the proposal.