API Response Length Design Guide
When designing REST APIs, response size and field character limits are often overlooked. However, proper length design directly impacts performance, user experience, and data consistency. This article provides practical guidelines for API response character design.
Recommended Field Lengths
| Field | Recommended Max | Design Consideration |
|---|---|---|
| Username | 50 characters | Consider UI display width and uniqueness constraints |
| Email address | 254 characters | Per RFC 5321 specification |
| Display name | 100 characters | Allow room for multilingual names |
| Short description | 200 characters | Designed for list views |
| Full description | 2,000–5,000 characters | Account for HTML tags in rich text |
| Error message | 200 characters | Concise and specific for end users |
| URL | 2,048 characters | Matches browser implementation limits |
| Tags/Labels | 50 characters | Balance searchability and readability |
Response Size Optimization
For mobile APIs, aim for responses under 50KB per request. Use pagination to limit list responses to 20–50 items. Consider field selection mechanisms (like GraphQL or REST fields parameters) to let clients request only what they need. Use gzip compression rather than shortening JSON key names, which hurts debuggability.
Error Message Design
Structure error messages in two layers: a developer-facing detail field (up to 500 characters with technical information) and a user-facing message field (under 100 characters in plain language). For validation errors, return per-field messages under 80 characters each to prevent UI layout issues.
Conclusion
API response length design is a critical decision affecting both performance and data quality. Define clear limits per field, keep error messages concise yet specific, and use pagination for large datasets. Use Character Counter to verify field lengths during API design.