Field Selection

Basic Field Selection

By default, api.vision returns all fields for a resource. To select only specific fields, use the fields query parameter with a comma-separated list of field names:

GET /users?fields=id,username,email

This returns only the id, username, and email fields for each user, omitting other fields like address, phone, etc.

Field Selection Benefits

Selecting only the fields you need offers several advantages:

• Reduces response payload size
• Improves network transfer speed
• Reduces client-side parsing time
• Minimizes data exposure (useful for sensitive fields)

Required Fields

Some fields are always included in responses, even if not explicitly requested:

• id: The primary identifier is always included
• Foreign keys: Fields that represent relationships (like userId) are included if needed for consistency

Selecting Fields from Related Resources

When expanding relationships (using expand), you can specify which fields to include from related resources using dot notation:

GET /posts?fields=id,title,content,author.id,author.name&expand=author

This returns the id, title, and content fields from posts, and only the id and name fields from the expanded author.

Advanced Relationship Field Selection

For more complex scenarios with multiple relationships, you can be explicit about which fields to include for each expanded relationship:

GET /posts?
  fields=id,title,author.id,author.name,comments.id,comments.text&
  expand=author,comments

This example:

• Returns id and title fields from the post
• Expands the author relationship, including only id and name
• Expands the comments relationship, including only id and text

Nested Field Selection

For resources with nested objects, you can select specific nested fields using dot notation:

GET /products?fields=id,name,specs.dimensions,specs.weight

This returns the id and name fields from the product, and only the dimensions and weight fields from the specs object.

Excluding Fields

To exclude specific fields while including all others, use the exclude query parameter:

GET /users?exclude=password,ssn,creditCardNumber

This returns all fields except password, ssn, and creditCardNumber. This is particularly useful for omitting sensitive data.

Wildcard Selection

api.vision supports wildcard patterns for selecting fields that match a certain pattern:

GET /products?fields=id,name,price,*_date

This returns the id, name, and price fields, plus any field that ends with "_date" (like creation_date, update_date, etc.).

Field Groups

api.vision allows you to define field groups in your API configuration, making it easier to request common field sets:

GET /users?fields=@basic

If you've defined a "basic" field group for users that includes id, username, and email, this would return those fields.

You can combine field groups with individual fields:

GET /users?fields=@basic,phone,status

Combining with Other Query Features

Field selection can be combined with other query features:

GET /products?
  category=electronics&
  price_gte=100&
  sort=-rating&
  fields=id,name,price,rating&
  page=1&
  limit=20

Response Format

When using field selection, the response structure remains the same, but only includes the requested fields:

// Request: GET /users?fields=id,username,email

[
  {
    "id": 1,
    "username": "johndoe",
    "email": "john@example.com"
  },
  {
    "id": 2,
    "username": "janedoe",
    "email": "jane@example.com"
  }
]