Extra Data Types
Part of: FastAPI Basics
Explore FastAPI's support for advanced Python data types including UUID, datetime, timedelta, bytes, Decimal, and more with automatic validation and conversion.
What You'll Learn
- Use UUID for universally unique identifiers in path parameters
- Handle datetime, date, time, and timedelta types with automatic ISO 8601 conversion
- Work with bytes, Decimal, and frozenset data types
- Understand automatic data conversion and validation for complex types
- Perform date/time calculations within FastAPI endpoints
Theory and Concepts
Extra Data Types
🎯 What You'll Learn
This lesson covers the official FastAPI "Extra Data Types" tutorial. You'll discover FastAPI's support for advanced Python data types beyond the basic int, float, str, and bool, with automatic validation, conversion, and documentation.
By the end of this lesson, you'll understand how to:
- Use UUID for universally unique identifiers in path parameters
- Handle datetime, date, time, and timedelta types with automatic ISO 8601 conversion
- Work with bytes, Decimal, and frozenset data types
- Understand automatic data conversion and validation for complex types
- Perform date/time calculations within FastAPI endpoints
📚 Supported Extra Data Types
FastAPI supports many additional Python data types with the same great features:
- Great editor support
- Data conversion from incoming requests
- Data conversion for response data
- Data validation
- Automatic annotation and documentation
🆔 UUID
Universally Unique Identifier, common as an ID in databases and systems.
- In requests/responses: Represented as a str
- Example: "550e8400-e29b-41d4-a716-446655440000"
📅 datetime.datetime
Python datetime.datetime objects.
- In requests/responses: Represented as ISO 8601 format string
- Example: "2008-09-15T15:53:00+05:00"
📆 datetime.date
Python datetime.date objects.
- In requests/responses: Represented as ISO 8601 date string
- Example: "2008-09-15"
⏰ datetime.time
Python datetime.time objects.
- In requests/responses: Represented as ISO 8601 time string
- Example: "14:23:55.003"
⏱️ datetime.timedelta
Python datetime.timedelta objects.
- In requests/responses: Represented as float of total seconds
- Example: 3600 (for 1 hour)
- Alternative: ISO 8601 time diff encoding (see Pydantic docs)
🧊 frozenset
Immutable set type.
- In requests: List is read, duplicates eliminated, converted to set
- In responses: Set is converted to list
- Schema: Specifies unique items using JSON Schema's uniqueItems
📄 bytes
Standard Python bytes.
- In requests/responses: Treated as str
- Schema: Specified as str with binary format
💰 Decimal
Standard Python Decimal for precise decimal arithmetic.
- In requests/responses: Handled the same as float
- Use case: Financial calculations requiring precision
🎯 Complete Example
Following the official FastAPI tutorial with modern Annotated syntax:
[Code Example]
📝 Request Example
URL:
[Code Example]
Request Body:
[Code Example]
Response:
[Code Example]
🔄 Automatic Conversions
UUID Conversion
[Code Example]
DateTime Conversion
[Code Example]
Timedelta Conversion
[Code Example]
Time Conversion
[Code Example]
🔧 Modern Annotated Syntax
The official FastAPI documentation now recommends using Annotated for better type hints and IDE support:
[Code Example]
Benefits of Annotated:
- Better IDE Support: More precise type information
- Cleaner Separation: Type and metadata are clearly separated
- Future-Proof: Aligns with Python's type annotation evolution
- Explicit: Makes the relationship between type and validation clear
🌟 Key Benefits
Type Safety
- Full IDE support with autocomplete
- Type checking catches errors at development time
- Clear function signatures show expected types
Automatic Validation
- Invalid UUIDs return HTTP 422 with clear error messages
- Invalid datetime formats are automatically rejected
- Type conversion happens transparently
Documentation Generation
- OpenAPI schema includes proper type information
- Interactive docs show expected formats
- Examples are automatically generated
Natural Python Operations
[Code Example]
💡 Best Practices
UUID Usage
[Code Example]
DateTime Handling
[Code Example]
Decimal for Financial Data
[Code Example]
Bytes for Binary Data
[Code Example]
🔍 Validation Examples
Valid Requests
UUID:
[Code Example]
DateTime:
[Code Example]
Timedelta:
[Code Example]
Invalid Requests
Invalid UUID:
[Code Example]
Invalid DateTime:
[Code Example]
Invalid Time:
[Code Example]
🔗 Advanced Usage
Combining Types in Models
[Code Example]
Custom Validation
[Code Example]
🔗 What's Next?
In the next lesson, you'll learn about Cookie Parameters, where you'll discover how to read and validate cookies using FastAPI's Cookie() function.
📖 Additional Resources
- FastAPI Official Tutorial - Extra Data Types
- Pydantic Data Types
- Python UUID Module
- Python Datetime Module
- ISO 8601 Standard
Helpful Hint
Import datetime types and UUID from their standard Python modules. FastAPI automatically converts between JSON strings and Python objects for these types.