Implementing Field Selection
1. Using Fields Query Parameter
| Style | Example |
|---|
| CSV | ?fields=id,name,email |
| JSON:API | ?fields[users]=name,email |
| GraphQL-like | ?fields=id,name,profile{bio,avatar} |
2. Implementing Sparse Fieldsets
JSON:API standard for per-resource-type field selection.
Example: Sparse Fieldsets
GET /articles?include=author&fields[articles]=title,body&fields[users]=name
| Pattern | Example |
|---|
| Dot notation | ?fields=id,author.name,author.email |
| Brace | ?fields=id,author{name,email} |
| Combined with expand | ?expand=author&fields=id,author.name |
4. Implementing Default Field Sets
| Field Group | Returned When |
|---|
| Always | Without fields param (full default) |
| List view | Compact set in collection endpoints |
| Detail view | Full set in singleton endpoint |
| On request | Heavy fields only with explicit fields |
5. Validating Requested Fields
| Check | Response |
|---|
| Unknown field | 400 + invalid field name |
| Forbidden field (auth) | 403 or silently omit |
| Empty selection | 400 or return defaults |
6. Handling Nested Field Selection
| Depth | Recommendation |
|---|
| 1 level | Simple flat selection |
| 2-3 levels | Use brace/dot notation |
| > 3 levels | Consider GraphQL instead |
7. Optimizing Database Queries
| Technique | Benefit |
|---|
| Project only requested columns | Less I/O, smaller result set |
| Skip JOINs when relations not needed | Faster query plan |
| Use covering indexes | Index-only scans |
Example: Combined Query
GET /users?fields=id,name&page=1&perPage=50&sort=name
9. Documenting Available Fields
| Documentation | Format |
|---|
| Field list | OpenAPI schema properties |
| Field descriptions | description per property |
| Default fields | Mark in description or extension |
10. Implementing Field Exclusion
| Param | Example |
|---|
exclude | ?exclude=largeBlob,internalNotes |
| Negation prefix | ?fields=*,-password,-internalNotes |