@xano/developer-mcp 1.0.27 → 1.0.29

package/dist/xanoscript_docs_auto/apis.md

@@ -0,0 +1,517 @@
+---
+applyTo: "apis/**/*.xs"
+---
+
+# APIs (Queries)
+
+HTTP API endpoint definitions with authentication, input validation, and response handling.
+
+## Quick Reference
+
+```xs
+query "<name>" verb=GET {
+  input { ... }
+  stack { ... }
+  response = $data
+  security { ... }
+  cache { ... }
+}
+```
+
+### HTTP Verbs
+| Verb | Purpose |
+|------|---------|
+| `GET` | Retrieve data |
+| `POST` | Create resource |
+| `PUT` | Full update |
+| `PATCH` | Partial update |
+| `DELETE` | Remove resource |
+
+---
+
+## Basic Query Definition
+
+### GET Endpoint
+
+```xs
+query "get_users" verb=GET {
+  input {
+    int? page default=1
+    int? per_page default=20
+    text? search
+  }
+  stack {
+    db.query user {
+      where = $db.user.name ilike? ("%" ~ $input.search ~ "%")
+      order_by = {field: "created_at", direction: "desc"}
+      return = {type: "list", paging: {per_page: $input.per_page, page: $input.page}}
+    } as $users
+  }
+  response = $users
+}
+```
+
+### POST Endpoint
+
+```xs
+query "create_user" verb=POST {
+  input {
+    text name filters=trim|min:1|max:100
+    email user_email filters=trim|lower
+    password pwd filters=min:8
+  }
+  stack {
+    // Check for duplicate email
+    db.has user {
+      where = $db.user.email == $input.user_email
+    } as $exists
+
+    precondition (!$exists) {
+      error_type = "inputerror"
+      error = "Email already registered"
+    }
+
+    // Create user
+    db.add user {
+      data = {
+        name: $input.name,
+        email: $input.user_email,
+        password: $input.pwd|password_hash,
+        created_at: now
+      }
+    } as $user
+  }
+  response = $user
+}
+```
+
+### PUT Endpoint
+
+```xs
+query "update_user" verb=PUT {
+  input {
+    int id
+    text name filters=trim|min:1|max:100
+    email user_email filters=trim|lower
+  }
+  stack {
+    db.edit user {
+      field_name = "id"
+      field_value = $input.id
+      data = {
+        name: $input.name,
+        email: $input.user_email,
+        updated_at: now
+      }
+    } as $user
+  }
+  response = $user
+}
+```
+
+### PATCH Endpoint
+
+```xs
+query "patch_user" verb=PATCH {
+  input {
+    int id
+    text? name filters=trim|min:1|max:100
+    email? user_email filters=trim|lower
+  }
+  stack {
+    var $updates { value = {} }
+
+    conditional {
+      if ($input.name != null) {
+        var.update $updates {
+          value = $updates|set:"name":$input.name
+        }
+      }
+    }
+
+    conditional {
+      if ($input.user_email != null) {
+        var.update $updates {
+          value = $updates|set:"email":$input.user_email
+        }
+      }
+    }
+
+    db.patch user {
+      field_name = "id"
+      field_value = $input.id
+      data = $updates|set:"updated_at":now
+    } as $user
+  }
+  response = $user
+}
+```
+
+### DELETE Endpoint
+
+```xs
+query "delete_user" verb=DELETE {
+  input {
+    int id
+  }
+  stack {
+    db.del user {
+      field_name = "id"
+      field_value = $input.id
+    }
+  }
+  response = {success: true}
+}
+```
+
+---
+
+## Authentication
+
+### Security Block
+
+```xs
+query "protected_endpoint" verb=GET {
+  security {
+    type = "auth"
+    // Requires authentication token
+  }
+  stack {
+    // $auth is available here
+    db.query order {
+      where = $db.order.user_id == $auth.id
+    } as $orders
+  }
+  response = $orders
+}
+```
+
+### No Authentication
+
+```xs
+query "public_endpoint" verb=GET {
+  security {
+    type = "none"
+  }
+  stack { ... }
+  response = $data
+}
+```
+
+### Custom Authentication
+
+```xs
+query "custom_auth" verb=GET {
+  security {
+    type = "custom"
+    function = "verify_api_key"
+  }
+  stack { ... }
+  response = $data
+}
+```
+
+---
+
+## GUID (URL Parameters)
+
+Route parameters in the URL:
+
+```xs
+query "get_user" verb=GET {
+  security {
+    guid = "user_id"  // URL: /user/{user_id}
+  }
+  input {
+    int user_id  // Comes from GUID
+  }
+  stack {
+    db.get user {
+      field_name = "id"
+      field_value = $input.user_id
+    } as $user
+
+    precondition ($user != null) {
+      error_type = "notfound"
+      error = "User not found"
+    }
+  }
+  response = $user
+}
+```
+
+### Multiple GUIDs
+
+```xs
+query "get_order_item" verb=GET {
+  security {
+    guid = "order_id,item_id"  // URL: /order/{order_id}/item/{item_id}
+  }
+  input {
+    int order_id
+    int item_id
+  }
+  stack { ... }
+}
+```
+
+---
+
+## Caching
+
+```xs
+query "get_products" verb=GET {
+  cache {
+    ttl = 300  // 5 minutes in seconds
+    key = "products:" ~ $input.category
+  }
+  input {
+    text category
+  }
+  stack {
+    db.query product {
+      where = $db.product.category == $input.category
+    } as $products
+  }
+  response = $products
+}
+```
+
+### Cache Invalidation
+
+```xs
+// In another endpoint that modifies products:
+query "update_product" verb=PUT {
+  stack {
+    db.edit product { ... } as $product
+
+    // Clear cache
+    redis.del {
+      key = "products:" ~ $product.category
+    }
+  }
+}
+```
+
+---
+
+## Response Headers
+
+```xs
+query "download_file" verb=GET {
+  stack {
+    storage.read_file_resource {
+      path = $input.file_path
+    } as $content
+
+    util.set_header {
+      name = "Content-Disposition"
+      value = "attachment; filename=\"" ~ $input.filename ~ "\""
+    }
+
+    util.set_header {
+      name = "Content-Type"
+      value = "application/octet-stream"
+    }
+  }
+  response = $content
+}
+```
+
+---
+
+## Input Validation
+
+### Input Filters
+
+```xs
+input {
+  text name filters=trim|min:1|max:100
+  email email filters=trim|lower
+  password pwd filters=min:8|minAlpha:1|minDigit:1
+  text phone filters=pattern:^\+?[0-9]{10,15}$
+  int quantity filters=min:1|max:1000
+  decimal price filters=min:0
+}
+```
+
+### Custom Validation
+
+```xs
+stack {
+  precondition ($input.end_date > $input.start_date) {
+    error_type = "inputerror"
+    error = "End date must be after start date"
+  }
+
+  precondition ($input.items|count > 0) {
+    error_type = "inputerror"
+    error = "At least one item is required"
+  }
+}
+```
+
+---
+
+## API Groups
+
+Organize related endpoints:
+
+```
+apis/
+├── users/
+│   ├── list.xs
+│   ├── get.xs
+│   ├── create.xs
+│   ├── update.xs
+│   └── delete.xs
+├── products/
+│   ├── list.xs
+│   ├── get.xs
+│   └── search.xs
+└── orders/
+    ├── create.xs
+    └── status.xs
+```
+
+### API Group Configuration
+
+```xs
+api_group "users" {
+  base_path = "/users"
+  middleware = ["auth", "logging"]
+}
+```
+
+---
+
+## Streaming Responses
+
+```xs
+query "stream_data" verb=GET {
+  stack {
+    api.stream {
+      content_type = "text/event-stream"
+      run {
+        foreach ($large_dataset) {
+          each as $item {
+            api.stream.write {
+              data = $item|json_encode ~ "\n"
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+---
+
+## File Uploads
+
+```xs
+query "upload_file" verb=POST {
+  input {
+    file document
+    text? description
+  }
+  stack {
+    storage.create_file_resource {
+      name = $input.document.name
+      content = $input.document
+    } as $stored_file
+
+    db.add document {
+      data = {
+        path: $stored_file.path,
+        name: $input.document.name,
+        size: $input.document.size,
+        mime: $input.document.mime,
+        description: $input.description,
+        uploaded_at: now
+      }
+    } as $record
+  }
+  response = $record
+}
+```
+
+---
+
+## Common Patterns
+
+### List with Filtering
+
+```xs
+query "list_products" verb=GET {
+  input {
+    int? page default=1
+    int? per_page default=20
+    text? category
+    decimal? min_price
+    decimal? max_price
+    text? sort default="created_at"
+    text? order default="desc"
+  }
+  stack {
+    db.query product {
+      where = $db.product.active == true
+            && $db.product.category ==? $input.category
+            && $db.product.price >=? $input.min_price
+            && $db.product.price <=? $input.max_price
+      order_by = {field: $input.sort, direction: $input.order}
+      return = {type: "list", paging: {per_page: $input.per_page, page: $input.page}}
+    } as $products
+  }
+  response = $products
+}
+```
+
+### CRUD Resource
+
+```xs
+// GET /users - List
+query "list" verb=GET { ... }
+
+// GET /users/{id} - Get one
+query "get" verb=GET {
+  security { guid = "id" }
+  ...
+}
+
+// POST /users - Create
+query "create" verb=POST { ... }
+
+// PUT /users/{id} - Update
+query "update" verb=PUT {
+  security { guid = "id" }
+  ...
+}
+
+// DELETE /users/{id} - Delete
+query "delete" verb=DELETE {
+  security { guid = "id" }
+  ...
+}
+```
+
+### Search Endpoint
+
+```xs
+query "search" verb=GET {
+  input {
+    text q filters=trim|min:2
+    int? limit default=20
+  }
+  stack {
+    db.query product {
+      where = $db.product.name ilike ("%" ~ $input.q ~ "%")
+            || $db.product.description search $input.q
+      order_by = {field: "name", direction: "asc"}
+      return = {type: "list", paging: {per_page: $input.limit}}
+    } as $results
+  }
+  response = $results
+}
+```