metabuilder/schemas/package-schemas/examples/advanced-features/api/rest.json

{
  "$schema": "https://metabuilder.dev/schemas/api.schema.json",
  "schemaVersion": "1.0.0",
  "package": "advanced-features",
  "description": "Advanced REST API with authentication and rate limiting",
  "basePath": "/api",
  "version": "v1",
  "auth": {
    "type": "jwt",
    "tokenLocation": "header",
    "headerName": "Authorization",
    "scheme": "Bearer",
    "secret": "${JWT_SECRET}",
    "expiresIn": 3600,
    "issuer": "advanced-features-api"
  },
  "rateLimit": {
    "enabled": true,
    "windowMs": 900000,
    "maxRequests": 100,
    "message": "Too many requests, please try again later",
    "keyGenerator": "ip"
  },
  "cors": {
    "enabled": true,
    "origin": ["http://localhost:3000", "https://example.com"],
    "credentials": true,
    "methods": ["GET", "POST", "PUT", "PATCH", "DELETE"],
    "allowedHeaders": ["Content-Type", "Authorization"],
    "exposedHeaders": ["X-Total-Count", "X-Page-Count"]
  },
  "routes": [
    {
      "id": "list_orders",
      "path": "/orders",
      "method": "GET",
      "handler": "handlers.orders.list",
      "description": "List orders with pagination and filtering",
      "auth": {
        "required": true,
        "permissions": ["orders.read"]
      },
      "rateLimit": {
        "maxRequests": 60
      },
      "queryParams": {
        "page": {
          "type": "integer",
          "default": 1,
          "min": 1
        },
        "limit": {
          "type": "integer",
          "default": 20,
          "min": 1,
          "max": 100
        },
        "status": {
          "type": "string",
          "enum": ["pending", "processing", "shipped", "delivered", "cancelled", "refunded"]
        },
        "customerId": {
          "type": "uuid"
        },
        "sort": {
          "type": "string",
          "default": "-createdAt"
        }
      },
      "response": {
        "200": {
          "description": "List of orders",
          "type": "OrderListResponse"
        },
        "401": {
          "description": "Unauthorized"
        },
        "403": {
          "description": "Forbidden"
        }
      }
    },
    {
      "id": "create_order",
      "path": "/orders",
      "method": "POST",
      "handler": "handlers.orders.create",
      "description": "Create a new order",
      "auth": {
        "required": true,
        "permissions": ["orders.create"]
      },
      "validation": {
        "body": "CreateOrderRequest"
      },
      "middleware": ["validateCart", "checkInventory"],
      "response": {
        "201": {
          "description": "Order created",
          "type": "Order"
        },
        "400": {
          "description": "Invalid request"
        },
        "422": {
          "description": "Validation failed"
        }
      }
    },
    {
      "id": "get_order",
      "path": "/orders/:id",
      "method": "GET",
      "handler": "handlers.orders.get",
      "description": "Get order by ID",
      "auth": {
        "required": true,
        "permissions": ["orders.read"]
      },
      "params": {
        "id": {
          "type": "uuid",
          "required": true
        }
      },
      "queryParams": {
        "include": {
          "type": "array",
          "items": {
            "type": "string",
            "enum": ["items", "customer", "shipping"]
          }
        }
      },
      "response": {
        "200": {
          "description": "Order details",
          "type": "Order"
        },
        "404": {
          "description": "Order not found"
        }
      }
    },
    {
      "id": "update_order",
      "path": "/orders/:id",
      "method": "PATCH",
      "handler": "handlers.orders.update",
      "description": "Update order",
      "auth": {
        "required": true,
        "permissions": ["orders.update"]
      },
      "params": {
        "id": {
          "type": "uuid",
          "required": true
        }
      },
      "validation": {
        "body": "UpdateOrderRequest"
      },
      "response": {
        "200": {
          "description": "Order updated",
          "type": "Order"
        },
        "404": {
          "description": "Order not found"
        }
      }
    },
    {
      "id": "cancel_order",
      "path": "/orders/:id/cancel",
      "method": "POST",
      "handler": "handlers.orders.cancel",
      "description": "Cancel an order",
      "auth": {
        "required": true,
        "permissions": ["orders.cancel"]
      },
      "params": {
        "id": {
          "type": "uuid",
          "required": true
        }
      },
      "validation": {
        "body": {
          "reason": {
            "type": "string",
            "required": true,
            "minLength": 10
          }
        }
      },
      "response": {
        "200": {
          "description": "Order cancelled",
          "type": "Order"
        },
        "400": {
          "description": "Cannot cancel order in current status"
        }
      }
    },
    {
      "id": "webhook_shipment",
      "path": "/webhooks/shipment",
      "method": "POST",
      "handler": "handlers.webhooks.shipment",
      "description": "Webhook for shipment tracking updates",
      "auth": {
        "required": true,
        "type": "apiKey",
        "location": "header",
        "name": "X-Webhook-Secret"
      },
      "validation": {
        "body": "ShipmentWebhook"
      }
    }
  ],
  "middleware": [
    "logger",
    "cors",
    "bodyParser",
    "rateLimit"
  ]
}