Request Forms
Part of: FastAPI Basics
Learn how to receive form data instead of JSON using FastAPI's Form class for handling HTML form submissions.
What You'll Learn
- Understand how to receive form data instead of JSON
- Learn to use the Form class from FastAPI
- Understand the difference between form data and JSON data
- Practice creating endpoints that accept form fields
Theory and Concepts
Request Forms
🎯 What You'll Learn
- How to receive form data instead of JSON in your FastAPI endpoints
- Understanding the difference between form data and JSON data
- Using the Form class from FastAPI for form field validation
- When to use form data vs JSON in your API design
📚 Theory
When you need to receive form fields instead of JSON, you can use Form. This is particularly useful when dealing with HTML forms or when integrating with systems that send data as form-encoded rather than JSON.
Why Form Data?
HTML forms (<form></form>) send data to the server using a "special" encoding that's different from JSON. This encoding is called application/x-www-form-urlencoded (or multipart/form-data for file uploads).
For example, in OAuth2 "password flow", the specification requires sending username and password as form fields, not JSON.
Import Form
First, import Form from fastapi:
[Code Example]
Define Form Parameters
Create form parameters the same way you would for Body or Query:
[Code Example]
🔧 Key Concepts
Form vs JSON
- JSON data: Content-Type: application/json
[Code Example]
- Form data: Content-Type: application/x-www-form-urlencoded
[Code Example]
Form Class Features
Form is a class that inherits directly from Body, so you can use the same configurations:
- Validation
- Examples
- Aliases (e.g., user-name instead of username)
- Documentation
[Code Example]
Explicit Form Declaration
To declare form bodies, you need to use Form explicitly. Without it, the parameters would be interpreted as query parameters or body (JSON) parameters.
💡 Best Practices
- Use form data for HTML form submissions
- Use form data when integrating with OAuth2 password flow
- Use JSON for API-to-API communication
- Always validate form data with appropriate constraints
- Use descriptive parameter names that match HTML form field names
- Consider using form data for simple key-value pairs
🚫 Common Pitfalls
- Forgetting to use Form(): Without Form(), parameters become query parameters
- Mixing form and JSON: Don't mix form fields and JSON body in the same endpoint
- Wrong Content-Type: Ensure clients send application/x-www-form-urlencoded
- Missing validation: Always add appropriate validation to form fields
- Security concerns: Never log or expose passwords in responses
🔗 Additional Resources
- FastAPI Form Data Documentation
- HTML Forms - MDN
- OAuth2 Password Flow
Helpful Hint
Import Form from fastapi and use it as a parameter default like Form() instead of Body().