@xano/developer-mcp 1.0.25 → 1.0.27

package/dist/xanoscript_docs_auto/apis.md

@@ -1,517 +0,0 @@
----
-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
-}
-```