{
  "openapi": "3.1.0",
  "info": {
    "title": "harlakshsingh.com API",
    "description": "Read-only public API for the personal website of Harlaksh Singh. No auth, no write operations. The unversioned /api/posts alias always serves the current version. Static snapshots of each payload are served alongside at the matching .json URL for the static host.",
    "version": "1.0.0"
  },
  "x-versioning-policy": {
    "strategy": "URL path versioning (/api/v1/...)",
    "current": "v1",
    "unversionedAlias": "/api/posts always serves the current version; prefer versioned paths for integrations",
    "compatibility": "Additive changes (new fields, new endpoints) do not trigger a new version. Consumers must ignore unknown fields.",
    "deprecation": "Breaking changes ship as a new version. The previous version keeps working for at least 6 months and advertises Sunset and Deprecation response headers with the retirement date."
  },
  "servers": [
    { "url": "https://harlakshsingh.com", "description": "Production" }
  ],
  "paths": {
    "/api/posts": {
      "get": {
        "operationId": "listRecentPosts",
        "summary": "List recent blog posts",
        "description": "Returns metadata (slug, title, date, category, excerpt) for the 4 most recent blog posts. Unversioned alias for the current version. Full post bodies are available as rendered HTML at /blog/{slug}.",
        "responses": {
          "200": {
            "description": "Recent posts",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "description": "The 4 most recent blog posts, newest first.",
                  "items": {
                    "type": "object",
                    "description": "Public metadata for one blog post.",
                    "required": ["slug", "title", "date", "category", "excerpt"],
                    "properties": {
                      "slug": { "type": "string", "description": "URL slug; full post at /blog/{slug}", "example": "indexing-the-internet" },
                      "title": { "type": "string", "description": "Post title", "example": "Checkstack - A Tech Lookup Tool" },
                      "date": { "type": "string", "description": "Publish date (YYYY-MM-DD)", "example": "2024-02-12" },
                      "category": { "type": "string", "description": "Post category", "example": "Thoughts" },
                      "excerpt": { "type": "string", "description": "One-line summary" }
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Could not load posts",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "description": "Structured API error.",
                  "required": ["error"],
                  "properties": {
                    "error": {
                      "type": "object",
                      "description": "Error detail with a stable code and a recovery hint.",
                      "required": ["code", "message"],
                      "properties": {
                        "code": { "type": "string", "description": "Stable machine-readable code", "example": "posts_unavailable" },
                        "message": { "type": "string", "description": "Human-readable message with a recovery hint", "example": "Could not load posts. Retry later or browse https://harlakshsingh.com/blog instead." }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/posts": {
      "get": {
        "operationId": "listRecentPostsV1",
        "summary": "List recent blog posts (v1)",
        "description": "Versioned form of listRecentPosts. Same payload and guarantees; prefer this path for integrations so future versions cannot silently change behavior.",
        "responses": {
          "200": {
            "description": "Recent posts",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "description": "The 4 most recent blog posts, newest first (API v1).",
                  "items": {
                    "type": "object",
                    "description": "Public metadata for one blog post (API v1).",
                    "required": ["slug", "title", "date", "category", "excerpt"],
                    "properties": {
                      "slug": { "type": "string", "description": "URL slug; full post at /blog/{slug}", "example": "indexing-the-internet" },
                      "title": { "type": "string", "description": "Post title", "example": "Checkstack - A Tech Lookup Tool" },
                      "date": { "type": "string", "description": "Publish date (YYYY-MM-DD)", "example": "2024-02-12" },
                      "category": { "type": "string", "description": "Post category", "example": "Thoughts" },
                      "excerpt": { "type": "string", "description": "One-line summary" }
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Could not load posts",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "description": "Structured API error.",
                  "required": ["error"],
                  "properties": {
                    "error": {
                      "type": "object",
                      "description": "Error detail with a stable code and a recovery hint.",
                      "required": ["code", "message"],
                      "properties": {
                        "code": { "type": "string", "description": "Stable machine-readable code", "example": "posts_unavailable" },
                        "message": { "type": "string", "description": "Human-readable message with a recovery hint", "example": "Could not load posts. Retry later or browse https://harlakshsingh.com/blog instead." }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/posts.json": {
      "get": {
        "operationId": "listRecentPostsStaticSnapshot",
        "summary": "List recent blog posts (static snapshot)",
        "description": "Same payload as GET /api/posts, prerendered to a static JSON file for the static host.",
        "responses": {
          "200": {
            "description": "Recent posts",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "description": "The 4 most recent blog posts, newest first.",
                  "items": {
                    "type": "object",
                    "description": "Public metadata for one blog post.",
                    "required": ["slug", "title", "date", "category", "excerpt"],
                    "properties": {
                      "slug": { "type": "string", "description": "URL slug" },
                      "title": { "type": "string", "description": "Post title" },
                      "date": { "type": "string", "description": "Publish date (YYYY-MM-DD)" },
                      "category": { "type": "string", "description": "Post category" },
                      "excerpt": { "type": "string", "description": "One-line summary" }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}