Query Capabilities

Overview

api.vision automatically creates a RESTful API for your resources with full CRUD operations. Beyond the basic operations, the API supports a rich query language that lets you:

• Filter resources based on field values
• Sort results in ascending or descending order
• Paginate large result sets
• Select specific fields to include in responses
• Expand relationships to include related resources

These capabilities are accessed through query parameters in your API requests.

Basic Endpoints

For each resource (e.g., "users"), api.vision automatically creates the following endpoints:

Query Features

Combining Query Features

You can combine multiple query features in a single request to create powerful, targeted API calls:

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

This request:

1. Filters for electronics products with a price of 100 or more
2. Sorts by rating (descending) and then by price (ascending)
3. Returns only the id, name, price, and rating fields
4. Returns the first page of results with 20 items per page

Response Format

By default, api.vision returns JSON responses. For list endpoints, the response is an array of resource objects:

[
  {
    "id": 1,
    "name": "Smartphone X",
    "price": 699.99,
    "category": "electronics",
    "inStock": true
  },
  {
    "id": 2,
    "name": "Laptop Pro",
    "price": 1299.99,
    "category": "electronics",
    "inStock": true
  }
]

For single resource endpoints, the response is a single object:

{
  "id": 1,
  "name": "Smartphone X",
  "price": 699.99,
  "category": "electronics",
  "inStock": true
}

Pagination Headers

When using pagination, api.vision includes helpful headers in the response:

Error Handling

When an error occurs, api.vision returns an appropriate HTTP status code and a JSON object with error details:

{
  "status": 404,
  "error": "Not Found",
  "message": "Resource with id '123' not found",
  "path": "/users/123"
}

Advanced Example

Here's a comprehensive example showing different query capabilities combined:

[
  {
    "id": 42,
    "title": "Advanced API Design Patterns",
    "createdAt": "2023-04-15T14:32:10Z",
    "author": {
      "username": "techguru"
    }
  },
  {
    "id": 39,
    "title": "The Future of Web Development",
    "createdAt": "2023-04-12T09:45:22Z",
    "author": {
      "username": "webwizard"
    }
  },
  {
    "id": 31,
    "title": "Mastering Microservices",
    "createdAt": "2023-04-05T16:20:45Z",
    "author": {
      "username": "techguru"
    }
  }
]

Next Steps

To learn more about each query capability in detail, check out the specific guides:

• Filtering Guide - Learn all the filtering operators and techniques
• Sorting Guide - How to sort resources by multiple fields
• Pagination Guide - Control result set size and navigate through pages
• Field Selection Guide - Select only the fields you need
• Relationship Expansion Guide - Include related resources in responses