Multiple aliases for query parameters

[tomgrin10]

First check

• I added a very descriptive title to this issue.
• I used the GitHub search to find a similar issue and didn't find it.
• I searched the FastAPI documentation, with the integrated search.
• I already searched in Google "How to X in FastAPI" and didn't find any information.
• I already read and followed all the tutorial in the docs and didn't find an answer.
• I already checked if it is not related to FastAPI but to Pydantic.
• I already checked if it is not related to FastAPI but to Swagger UI.
• I already checked if it is not related to FastAPI but to ReDoc.
• After submitting this, I commit to:
  • Read open issues with questions until I find 2 issues where I can help someone and add a comment to help there.
  • Or, I already hit the "watch" button in this repository to receive notifications and I commit to help at least 2 people that ask questions in the future.
  • Implement a Pull Request for a confirmed bug.

Example

I would like to be able to do this:

from fastapi import FastAPI, Query

app = FastAPI()


@app.get("/")
def get(query: Optional[str] = Query(None, alias=['q', 'query']):
    return query

Description

Currently to give a query parameter multiple aliases, you need to declare multiple query parameters.

The solution you would like

Being able to give a list of aliases to the alias arg of the Query class.

Query(alias=['q', 'query'])

Of course backwards compatibility won'y break, as alias arg would be of type Optional[Union[str, Iterable[str]]].
You would still be able to do this:

Query(alias='q')

Describe alternatives you've considered

@Kludex mentioned creating a new argument aliases

Query(aliases=['q', 'query'])

[Kludex]

It probably should accept a str as well or maybe an alternative solution could be a field aliases.

[tomgrin10]

It probably should accept a str as well or maybe an alternative solution could be a field aliases.

Yes, my intention was not to break compatibility and make it accept both an str and a Iterable[str], I'll edit my issue to make it more clear

[SirTelemak]

alias goes from pydantic so we can't make in on FastAPI layer (there is__slots__ defined for base class) as I can se it for now

[tomgrin10]

alias goes from pydantic so we can't make in on FastAPI layer (there is__slots__ defined for base class) as I can se it for now

That sucks.
Maybe duplicate the query parameter object for each alias?

[SirTelemak]

At first I think you should look/open similar issue for Pydantic. Maybe there some workarounds or it's planned feature. Multiple params forone object seems wrong

[tomgrin10]

At first I think you should look/open similar issue for Pydantic. Maybe there some workarounds or it's planned feature. Multiple params forone object seems wrong

Yea, I agree it's kinda hackish.
But if pydantic doesn't plan on supporting it, maybe it's the way to go.

[Kludex]

Maybe useful: pydantic/pydantic#324 (2 years old)

[tomgrin10]

So it doesn't seem like a pydantic solution is gonna happen any time soon, is there any progress on this?

[pmav99]

is there any progress on this?

Opening a ticket with your proposal on the pydantic bug-tracker would probably help. Making a pull request even more so, but asking for some initial feedback on the API would probably be a good idea.

[NoahCardoza]

I think I found a possible solution without modifying pydantic. Not sure if it will be officially merged in but I'll try to submit a PR in the coming days.

Hopefully it helps a few people!

[ycd]

@NoahCardoza can you provide an example?

[NoahCardoza]

Still working out the kinks, but it looks like it's possible since pydantic collects any extra kwargs inside an extra property. I don't have the project open but I'll try to explain that changes and add some screenshots/examples after I get out of my first wave of meetings today 💀

[NoahCardoza]

Alright, so after more digging my original statement was incorrect. I was using the Query class:

@app.get("/")
def get(query: str = Query(None, aliases=['query', 'q'])):
    return query

However, pydantic's ModelField does not have a catch all. One solution to this would be something along the lines of:

class MultiAliasablModelField(ModelField):
    def __init__(self, *args, aliases: Optional[List[str]] = None, **kwargs) -> None:
        super().__init__(*args, **kwargs)
        self.aliases = aliases

    def __repr_args__(self) -> str:
        args = super().__repr_args__()
        if self.aliases:
            args.append(('aliases', self.aliases))
        return args

This would require changes to the return annotations for the *_field functions, as well as other minor changes to handle the aliases property.

The get_param_field would then be able to pass the aliases via field_info.extra.get('aliases').

I've to to run at the moment, but I'll fork/branch and try to get a complete example ready ASAP.

[NoahCardoza]

Here is a working fix NoahCardoza/fastapi:feature/multiple-aliases! I need to do a little clean up and update the docs etc.

You'll also noticed a TODO which is looking more like a FIX now that I think about it... It's 4 AM.

Anyways, I'm not sure how a field with multiple aliases should properly render an error when it's a required field.

For reference, I'm using this code to test:

from typing import Optional
from pydantic import Required
from fastapi import FastAPI, Query

app = FastAPI()


@app.get("/")
def get(
        question: str = Query(Required, aliases=('q', 'question')),
        answer: Optional[int] = Query(None, aliases=('a', 'answer'))
    ):
    return {
        'question': question,
        'answer': answer,
    }


app.setup()

And I'm using this script to test:

req() {
  curl -w "\n" "http://127.0.0.1:8000$1"
}

req
req "/?q=What%27s%20the%20answer%20to%20the%20universe?"
req "/?question=What%27s%20the%20answer%20to%20the%20universe?"
req "/?q=What%27s%20the%20answer%20to%20the%20universe?&a=42"
req "/?question=What%27s%20the%20answer%20to%20the%20universe?&answer=42"

Which you can diff against:

{"detail":[{"loc":["query",["q","question"]],"msg":"field required","type":"value_error.missing"}]}
{"question":"What's the answer to the universe?","answer":null}
{"question":"What's the answer to the universe?","answer":null}
{"question":"What's the answer to the universe?","answer":42}
{"question":"What's the answer to the universe?","answer":42}

[zhqu1148980644]

How's this going on?

[vbigbang]

How's this going on?

[NoahCardoza]

Sorry @vbigbang and @zhqu1148980644, I've become busy with other things at the moment. If I can get back to this I will, but if anyone else wants to take it up from where I left off, feel free!

[iamthen0ise]

Sorry, but how this feature would appear in Swagger/OpenAPI generated by FastAPI?

[NoahCardoza]

@iamthen0ise If I remember correctly, I think that was one of the issues I was stuck on before I ran out of time... I'm not exactly sure.

[tiangolo]

This will be possible with Pydantic v2, and once FastAPI is updated for Pydantic v2. 🚀

Because of that, it would actually be more of a Pydantic issue than a FastAPI issue. 🤓

Sorry for the long delay! 🙈 I wanted to personally address each issue and they piled up through time, but now I'm checking each one in order.

[github-actions[bot]]

Assuming the original need was handled, this will be automatically closed now. But feel free to add more comments or create new issues or PRs.

[bkis]

This will be possible with Pydantic v2, and once FastAPI is updated for Pydantic v2.
Because of that, it would actually be more of a Pydantic issue than a FastAPI issue.

But this question by @iamthen0ise is still a FastAPI issue, isn't it? How would this be handled?

[tiangolo]

Not sure yet how it would be handled. I haven't worked on that yet.

[bkis]

I am not sure if this is helpful, but I'd like to share my perspective on this matter. As far as I see there are two kinds of related needs in functionality that come with very different impact on the existing implementation:

1. The less intrusive way: The ability to define one "public" and one "internal" version/alias for parameter names to have e.g. camel-cased parameters (someParam) published via the API, while working with snake-cased (some_param) parameters internally. There'd be no ambiguity about what to display in the swagger doc, because there'd be only one "public" version of each parameter.
2. Allowing arbitrary public parameter aliases. I can see that this might be handy in some situations, but it comes with some difficulties (like the above-mentioned swagger question) and might also unnecessarily bloat the framework. But maybe I just overlook an important use case for this.

I'd argue it's kind of a bummer no. 1 isn't possible.
Anyway, thank you a lot for this beautiful framework! I really enjoy working with it so far!

[padrepitufo]

Given Pydantic V2 is out (and has been for a while). Is there a documented way of achieving this? I'm assuming it won't just work (per the swagger/openapi question). I have seen that there does seem to be a validation_alias field for Query that would take multiple aliases - would it then be via pydantic's AliasChoices ?

I am noticing this tidbit https://github.com/tiangolo/fastapi/blob/master/fastapi/params.py#L316-L317

  315      ...
  316      # TODO: update when deprecating Pydantic v1, import these types
  317      # validation_alias: str | AliasPath | AliasChoices | None
  318      validation_alias: Union[str, None] = None,
  319      ...