If you are starting with **FastAPI**, you might not need this.
If you are starting with **FastAPI**, you might not need this.
By default, **FastAPI** will return the responses using Starlette's `JSONResponse`.
By default, **FastAPI** will return the responses using Starlette's `JSONResponse`.
But you can override it.
You can override it by returning a `Response` directly, <ahref="https://fastapi.tiangolo.com/tutorial/response-directly/"target="_blank">as seen in a previous section</a>.
## Use `UJSONResponse`
But if you return a `Response` directly, the data won't be automatically converted, and the documentation won't be automatically generated (for example, including the specific "media type", in the HTTP header `Content-Type`).
For example, if you are squeezing performance, you can use `ujson` and set the response to be Starlette's `UJSONResponse`.
But you can also declare the `Response` that you want to be used, in the *path operation decorator*.
### Import `UJSONResponse`
The contents that you return from your *path operation function* will be put inside of that `Response`.
```Python hl_lines="2"
And if that `Response` has a JSON media type (`application/json`), like is the case with the `JSONResponse` and `UJSONResponse`, the data you return will be automatically converted (and filtered) with any Pydantic `response_model` that you declared in the *path operation decorator*.
{!./src/custom_response/tutorial001.py!}
```
!!! note
## Use `UJSONResponse`
Notice that you import it directly from `starlette.responses`, not from `fastapi`.
### Make your path operation use it
For example, if you are squeezing performance, you can install and use `ujson` and set the response to be Starlette's `UJSONResponse`.
Make your path operation use `UJSONResponse` as the response class using the parameter `content_type`:
Import the `Response` class (sub-class) you want to use and declare it in the *path operation decorator*.
```Python hl_lines="7"
```Python hl_lines="2 7"
{!./src/custom_response/tutorial001.py!}
{!./src/custom_response/tutorial001.py!}
```
```
!!! note
Notice that you import it directly from `starlette.responses`, not from `fastapi`.
!!! info
!!! info
The parameter is called `content_type` because it will also be used to define the "media type" of the response.
The parameter `response_class` will also be used to define the "media type" of the response.
And will be documented as such in OpenAPI.
In this case, the HTTP header `Content-Type` will be set to `application/json`.
And it will be documented as such in OpenAPI.
## HTML Response
## HTML Response
To return a response with HTML directly from **FastAPI**, use `HTMLResponse`.
To return a response with HTML directly from **FastAPI**, use `HTMLResponse`.
### Import `HTMLResponse`
* Import `HTMLResponse`.
* Pass `HTMLResponse` as the parameter `content_type` of your path operation.
```Python hl_lines="2"
```Python hl_lines="2 7"
{!./src/custom_response/tutorial002.py!}
{!./src/custom_response/tutorial002.py!}
```
```
!!! note
!!! note
Notice that you import it directly from `starlette.responses`, not from `fastapi`.
Notice that you import it directly from `starlette.responses`, not from `fastapi`.
### Define your `content_type` class
Pass `HTMLResponse` as the parameter `content_type` of your path operation:
```Python hl_lines="7"
{!./src/custom_response/tutorial002.py!}
```
!!! info
!!! info
The parameter is called `content_type` because it will also be used to define the "media type" of the response.
The parameter `response_class` will also be used to define the "media type" of the response.
In this case, the HTTP header `Content-Type` will be set to `text/html`.
In this case, the HTTP header `Content-Type` will be set to `text/html`.
And it will be documented as such in OpenAPI.
And it will be documented as such in OpenAPI.
### Return a Starlette `Response`
### Return a Starlette `Response`
You can also override the response directly in your path operation.
As seen in <ahref="https://fastapi.tiangolo.com/tutorial/response-directly/"target="_blank">another section</a>, you can also override the response directly in your path operation, by returning it.
If you return an object that is an instance of Starlette's `Response`, it will be used as the response directly.
The same example from above, returning an `HTMLResponse`, could look like:
The same example from above, returning an `HTMLResponse`, could look like:
```Python hl_lines="7"
```Python hl_lines="2 7 19"
{!./src/custom_response/tutorial003.py!}
{!./src/custom_response/tutorial003.py!}
```
```
!!! info
Of course, the `Content-Type` header will come from the the `Response` object your returned.
!!! warning
!!! warning
A `Response` returned directly by your path operation function won't be documented in OpenAPI and won't be visible in the automatic interactive docs.
A `Response` returned directly by your path operation function won't be documented in OpenAPI (for example, the `Content-Type` won't be documented) and won't be visible in the automatic interactive docs.
!!! info
Of course, the actual `Content-Type` header, status code, etc, will come from the `Response` object your returned.
### Document in OpenAPI and override `Response`
### Document in OpenAPI and override `Response`
If you want to override the response from inside of the function but at the same time document the "media type" in OpenAPI, you can use the `content_type` parameter AND return a `Response` object.
If you want to override the response from inside of the function but at the same time document the "media type" in OpenAPI, you can use the `response_class` parameter AND return a `Response` object.
The `content_type` class will then be used only to document the OpenAPI path operation, but your `Response` will be used as is.
The `response_class` will then be used only to document the OpenAPI path operation, but your `Response` will be used as is.
#### Return an `HTMLResponse` directly
#### Return an `HTMLResponse` directly
For example, it could be something like:
For example, it could be something like:
```Python hl_lines="7 23"
```Python hl_lines="7 23 21"
{!./src/custom_response/tutorial004.py!}
{!./src/custom_response/tutorial004.py!}
```
```
@ -100,16 +90,10 @@ In this example, the function `generate_html_response()` already generates a Sta
By returning the result of calling `generate_html_response()`, you are already returning a `Response` that will override the default **FastAPI** behavior.
By returning the result of calling `generate_html_response()`, you are already returning a `Response` that will override the default **FastAPI** behavior.
#### Declare `HTMLResponse` as `content_type`
But as you passed the `HTMLResponse` in the `response_class`, **FastAPI** will know how to document it in OpenAPI and the interactive docs as HTML with `text/html`:
But by declaring it also in the path operation decorator:
You can also declare the media type and many other details in OpenAPI using `responses`: <ahref="https://fastapi.tiangolo.com/tutorial/additional-responses/"target="_blank">Additional Responses in OpenAPI</a>.
There are some cases where you might need to convert a data type (like a Pydantic model) to something compatible with JSON (like a `dict`, `list`, etc).
For example, if you need to store it in a database.
For that, **FastAPI** provides a `jsonable_encoder()` function.
## Using the `jsonable_encoder`
Let's imagine that you have a database `fake_db` that only receives JSON compatible data.
For example, it doesn't receive `datetime` objects, as those are not compatible with JSON.
So, a `datetime` object would have to be converted to a `str` containing the data in <ahref="https://en.wikipedia.org/wiki/ISO_8601"target="_blank">ISO format</a>.
The same way, this database wouldn't receive a Pydantic model (an object with attributes), only a `dict`.
You can use `jsonable_encoder` for that.
It receives an object, like a Pydantic model, and returns a JSON compatible version:
```Python hl_lines="4 21"
{!./src/encoder/tutorial001.py!}
```
In this example, it would convert the Pydantic model to a `dict`, and the `datetime` to a `str`.
The result of calling it is something that can be encoded with the Python standard <ahref="https://docs.python.org/3/library/json.html#json.dumps"target="_blank">`json.dumps()`</a>.
It doesn't return a large `str` containing the data in JSON format (as a string). It returns a Python standard data structure (e.g. a `dict`) with values and sub-values that are all compatible with JSON.
!!! note
`jsonable_encoder` is actually used by **FastAPI** internally to convert data. But it is useful in many other scenarios.
When you create a **FastAPI***path operation* you can normally return any data from it: a `dict`, a `list`, a Pydantic model, a database model, etc.
By default, **FastAPI** would automatically convert that return value to JSON using the <ahref="https://fastapi.tiangolo.com/tutorial/encoder/"target="_blank">`jsonable_encoder`</a>.
Then, behind the scenes, it would put that JSON-compatible data (e.g. a `dict`) inside of a Starlette `JSONResponse` that would be used to send the response to the client.
But you can return a `JSONResponse` directly from your *path operations*.
It might be useful, for example, to return custom headers or cookies.
## Starlette `Response`
In fact, you can return any <ahref="https://www.starlette.io/responses/"target="_blank">Starlette `Response`</a> or any sub-class of it.
!!! tip
`JSONResponse` itself is a sub-class of `Response`.
And when you return a Starlette `Response`, **FastAPI** will pass it directly.
It won't do any data conversion with Pydantic models, it won't convert the contents to any type, etc.
This gives you a lot of flexibility. You can return any data type, override any data declaration or validation, etc.
## Using the `jsonable_encoder` in a `Response`
Because **FastAPI** doesn't do any change to a `Response` you return, you have to make sure it's contents are ready for it.
For example, you cannot put a Pydantic model in a `JSONResponse` without first converting it to a `dict` with all the data types (like `datetime`, `UUID`, etc) converted to JSON-compatible types.
For those cases, you can use the `jsonable_encoder` to convert your data before passing it to a response:
```Python hl_lines="4 6 20 21"
{!./src/response_directly/tutorial001.py!}
```
!!! note
Notice that you import it directly from `starlette.responses`, not from `fastapi`.
## Returning a custom `Response`
The example above shows all the parts you need, but it's not very useful yet, as you could have just returned the `item` directly, and **FastAPI** would put it in a `JSONResponse` for you, converting it to a `dict`, etc. All that by default.
Now, let's see how you could use that to return a custom response.
Let's say you want to return a response that is not available in the default <ahref="https://www.starlette.io/responses/"target="_blank">Starlette `Response`s</a>.
Let's say that you want to return <ahref="https://en.wikipedia.org/wiki/XML"target="_blank">XML</a>.
You could put your XML content in a string, put it in a Starlette Response, and return it:
```Python hl_lines="2 20"
{!./src/response_directly/tutorial002.py!}
```
## Notes
When you return a `Response` directly its data is not validated, converted (serialized), nor documented automatically.
But you can still <ahref="tutorial/additional-responses/"target="_blank">document it</a>.
In the next sections you will see how to use/declare these custom `Response`s while still having automatic data conversion, documentation, etc.
You will also see how to use them to set response Headers and Cookies.
Sebastián Ramírez
6 years ago
GitHub