{
  "openapi": "3.1.0",
  "info": {
    "title": "TajrobeHost Public Data API",
    "version": "1.0.0",
    "description": "Public, read-only hosting-company rankings and technical monitoring data. Measurements describe each company's public website, not every customer hosting plan. Attribution is required.",
    "contact": { "name": "TajrobeHost", "url": "https://tajrobehost.ir/contact" }
  },
  "servers": [{ "url": "https://tajrobehost.ir/api/v1" }],
  "paths": {
    "/hosting-rankings": {
      "get": {
        "operationId": "listHostingRankings",
        "summary": "List and filter hosting-company rankings",
        "parameters": [
          { "name": "id", "in": "query", "schema": { "type": "integer", "minimum": 1 } },
          { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 100 } },
          { "name": "status", "in": "query", "schema": { "type": "string", "enum": ["all", "online", "offline"], "default": "all" } },
          { "name": "sort", "in": "query", "schema": { "type": "string", "enum": ["technical_score", "response_ms", "uptime_percent", "security_score", "review_count", "name"], "default": "technical_score" } },
          { "name": "order", "in": "query", "schema": { "type": "string", "enum": ["asc", "desc"] } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 22 } },
          { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "headers": { "ETag": { "schema": { "type": "string" } } },
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RankingResponse" } } }
          },
          "405": { "description": "Method not allowed" },
          "500": { "description": "Internal server error with a request ID" }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "RankingResponse": {
        "type": "object",
        "required": ["api_version", "generated_at", "methodology", "pagination", "data"],
        "properties": {
          "api_version": { "type": "string", "examples": ["1.0"] },
          "data_scope": { "type": "string" },
          "generated_at": { "type": "string", "format": "date-time" },
          "latest_measurement_at": { "type": ["string", "null"], "format": "date-time" },
          "methodology": { "type": "object", "additionalProperties": true },
          "attribution": { "type": "object", "additionalProperties": true },
          "pagination": { "$ref": "#/components/schemas/Pagination" },
          "filters": { "type": "object", "additionalProperties": true },
          "data": { "type": "array", "items": { "$ref": "#/components/schemas/HostingCompany" } }
        }
      },
      "Pagination": {
        "type": "object",
        "properties": { "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "returned": { "type": "integer" } }
      },
      "HostingCompany": {
        "type": "object",
        "required": ["id", "name", "rank", "scores", "availability", "timings_ms"],
        "properties": {
          "id": { "type": "integer" }, "rank": { "type": "integer" }, "name": { "type": "string" },
          "profile_url": { "type": "string", "format": "uri" }, "official_website": { "type": ["string", "null"], "format": "uri" },
          "logo_url": { "type": ["string", "null"], "format": "uri" }, "category": { "type": "string" }, "summary": { "type": "string" },
          "locations": { "type": "array", "items": { "type": "string" } }, "features": { "type": "array", "items": { "type": "string" } },
          "scores": { "type": "object", "properties": { "technical": { "type": ["integer", "null"] }, "performance": { "type": ["integer", "null"] }, "security": { "type": ["integer", "null"] }, "security_grade": { "type": ["string", "null"] } } },
          "availability": { "type": "object", "properties": { "current_status": { "type": "string", "enum": ["online", "offline", "unknown"] }, "uptime_percent": { "type": ["number", "null"] }, "successful_checks": { "type": "integer" }, "sample_count": { "type": "integer" } } },
          "timings_ms": { "type": "object", "properties": { "total": { "type": ["number", "null"] }, "ttfb": { "type": ["number", "null"] }, "dns": { "type": ["number", "null"] }, "connect": { "type": ["number", "null"] }, "tls": { "type": ["number", "null"] } } },
          "http": { "type": "object", "properties": { "status_code": { "type": ["integer", "null"] } } },
          "security": { "type": "object", "additionalProperties": true }, "approved_review_count": { "type": "integer" },
          "last_checked_at": { "type": ["string", "null"], "format": "date-time" }
        }
      }
    }
  }
}