{
  "openapi": "3.0.3",
  "info": {
    "title": "FaithStack API",
    "description": "A curated collection of APIs, datasets, models, and tools designed to empower developers building technology that serves the faith community.",
    "version": "1.0.0",
    "contact": {
      "name": "FaithStack Support",
      "url": "https://faithstack.dev"
    },
    "license": {
      "name": "MIT",
      "url": "https://opensource.org/licenses/MIT"
    }
  },
  "servers": [
    {
      "url": "/api/v1",
      "description": "FaithStack API v1"
    }
  ],
  "paths": {
    "/resources": {
      "post": {
        "summary": "Submit resource",
        "description": "Submit a new resource for review. Resources will be reviewed before being published.",
        "operationId": "submitResource",
        "tags": [
          "Resources"
        ],
        "requestBody": {
          "description": "Resource data to submit",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SubmitResourceRequest"
              },
              "example": {
                "title": "Bible API",
                "description": "RESTful API for Bible verses and passages",
                "link": "https://api.bible.com",
                "author": "Bible Society",
                "type": "API",
                "license": "MIT",
                "tags": [
                  "bible",
                  "api",
                  "rest",
                  "scripture"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Resource submitted successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SubmitResourceResponse"
                },
                "example": {
                  "version": "v1",
                  "message": "Resource submitted successfully! It will be reviewed before being published.",
                  "resourceId": 123,
                  "status": "pending"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - Missing required fields",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "version": "v1",
                  "error": "Missing required fields: title, description, type"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "version": "v1",
                  "error": "Failed to submit resource"
                }
              }
            }
          }
        }
      },
      "get": {
        "summary": "Get resources",
        "description": "Retrieve approved resources with optional filtering and pagination",
        "operationId": "getResources",
        "tags": [
          "Resources"
        ],
        "parameters": [
          {
            "name": "type",
            "in": "query",
            "description": "Filter by resource type",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "API",
                "Dataset",
                "Model",
                "Project",
                "Tool",
                "Resource",
                "Event"
              ]
            },
            "example": "API"
          },
          {
            "name": "search",
            "in": "query",
            "description": "Search query across titles, descriptions, authors, and tags",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "bible"
          },
          {
            "name": "q",
            "in": "query",
            "description": "Alias for search parameter",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "machine learning"
          },
          {
            "name": "tags",
            "in": "query",
            "description": "Filter by tags (AND operation for multiple tags)",
            "required": false,
            "schema": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "style": "form",
            "explode": true,
            "example": [
              "ai",
              "python"
            ]
          },
          {
            "name": "author",
            "in": "query",
            "description": "Filter by author name",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "OpenAI"
          },
          {
            "name": "license",
            "in": "query",
            "description": "Filter by license type",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "MIT"
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Number of results per page",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            },
            "example": 20
          },
          {
            "name": "offset",
            "in": "query",
            "description": "Number of results to skip for pagination",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            },
            "example": 0
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved resources",
            "headers": {
              "X-API-Version": {
                "description": "API version",
                "schema": {
                  "type": "string",
                  "example": "v1"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourcesResponse"
                },
                "example": {
                  "version": "v1",
                  "resources": [
                    {
                      "id": "1",
                      "title": "Bible API",
                      "description": "RESTful API for Bible verses and passages",
                      "category": [
                        "api",
                        "bible"
                      ],
                      "author": "Bible Society",
                      "date": "2024-01-15T10:00:00Z",
                      "stars": 0,
                      "license": "MIT",
                      "tags": [
                        "bible",
                        "api",
                        "rest",
                        "scripture"
                      ],
                      "link": "https://api.bible.com",
                      "type": "API"
                    }
                  ],
                  "totalResults": 25,
                  "typeCounts": {
                    "API": 15,
                    "Dataset": 8,
                    "Event": 2
                  },
                  "pagination": {
                    "total": 25,
                    "limit": 50,
                    "offset": 0,
                    "hasMore": false
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "version": "v1",
                  "error": "Internal server error"
                }
              }
            }
          }
        }
      }
    },
    "/resources/types": {
      "get": {
        "summary": "Get resource types",
        "description": "Get all available resource types with counts",
        "operationId": "getResourceTypes",
        "tags": [
          "Resources"
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved resource types",
            "headers": {
              "X-API-Version": {
                "description": "API version",
                "schema": {
                  "type": "string",
                  "example": "v1"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResourceTypesResponse"
                },
                "example": {
                  "version": "v1",
                  "types": [
                    {
                      "type": "API",
                      "count": 15,
                      "category": "resource"
                    },
                    {
                      "type": "Dataset",
                      "count": 8,
                      "category": "resource"
                    },
                    {
                      "type": "Event",
                      "count": 2,
                      "category": "event"
                    }
                  ],
                  "totalTypes": 7
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "version": "v1",
                  "error": "Internal server error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "SubmitResourceRequest": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string",
            "description": "Resource title",
            "example": "Bible API"
          },
          "description": {
            "type": "string",
            "description": "Resource description",
            "example": "RESTful API for Bible verses and passages"
          },
          "link": {
            "type": "string",
            "format": "uri",
            "description": "Primary URL for the resource",
            "example": "https://api.bible.com"
          },
          "author": {
            "type": "string",
            "description": "Author or organization name",
            "example": "Bible Society"
          },
          "type": {
            "type": "string",
            "enum": [
              "API",
              "Dataset",
              "Model",
              "Project",
              "Tool",
              "Resource"
            ],
            "description": "Resource type",
            "example": "API"
          },
          "license": {
            "type": "string",
            "description": "License type",
            "example": "MIT"
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Associated tags",
            "example": [
              "bible",
              "api",
              "rest",
              "scripture"
            ]
          }
        },
        "required": [
          "title",
          "description",
          "type"
        ]
      },
      "SubmitResourceResponse": {
        "type": "object",
        "properties": {
          "version": {
            "type": "string",
            "description": "API version",
            "example": "v1"
          },
          "message": {
            "type": "string",
            "description": "Success message",
            "example": "Resource submitted successfully! It will be reviewed before being published."
          },
          "resourceId": {
            "type": "integer",
            "description": "ID of the submitted resource",
            "example": 123
          },
          "status": {
            "type": "string",
            "description": "Current status of the resource",
            "example": "pending"
          }
        },
        "required": [
          "version",
          "message",
          "resourceId",
          "status"
        ]
      },
      "Resource": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier for the resource",
            "example": "1"
          },
          "title": {
            "type": "string",
            "description": "Resource title",
            "example": "Bible API"
          },
          "description": {
            "type": "string",
            "description": "Resource description",
            "example": "RESTful API for Bible verses and passages"
          },
          "category": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Categories/tags associated with the resource",
            "example": [
              "api",
              "bible"
            ]
          },
          "author": {
            "type": "string",
            "description": "Author or organization name",
            "example": "Bible Society"
          },
          "date": {
            "type": "string",
            "format": "date-time",
            "description": "Creation date in ISO 8601 format",
            "example": "2024-01-15T10:00:00Z"
          },
          "stars": {
            "type": "integer",
            "description": "Star rating (currently always 0)",
            "example": 0
          },
          "license": {
            "type": "string",
            "nullable": true,
            "description": "License type",
            "example": "MIT"
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Associated tags",
            "example": [
              "bible",
              "api",
              "rest",
              "scripture"
            ]
          },
          "link": {
            "type": "string",
            "nullable": true,
            "description": "Primary URL for the resource",
            "example": "https://api.bible.com"
          },
          "type": {
            "type": "string",
            "description": "Resource type",
            "example": "API"
          },
          "start": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Event start date (for events only)",
            "example": "2024-05-15T09:00:00Z"
          },
          "end": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Event end date (for events only)",
            "example": "2024-05-17T17:00:00Z"
          },
          "location": {
            "type": "string",
            "nullable": true,
            "description": "Event location (for events only)",
            "example": "Austin, TX"
          },
          "url": {
            "type": "string",
            "nullable": true,
            "description": "Event URL (for events only)",
            "example": "https://christiandev.conf"
          }
        },
        "required": [
          "id",
          "title",
          "description",
          "category",
          "author",
          "date",
          "stars",
          "tags",
          "type"
        ]
      },
      "ResourcesResponse": {
        "type": "object",
        "properties": {
          "version": {
            "type": "string",
            "description": "API version",
            "example": "v1"
          },
          "resources": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Resource"
            },
            "description": "Array of resources"
          },
          "totalResults": {
            "type": "integer",
            "description": "Total number of resources matching the query",
            "example": 25
          },
          "typeCounts": {
            "type": "object",
            "additionalProperties": {
              "type": "integer"
            },
            "description": "Count of resources by type",
            "example": {
              "API": 15,
              "Dataset": 8,
              "Event": 2
            }
          },
          "pagination": {
            "$ref": "#/components/schemas/Pagination"
          },
          "filters": {
            "$ref": "#/components/schemas/AppliedFilters"
          }
        },
        "required": [
          "version",
          "resources",
          "totalResults",
          "typeCounts"
        ]
      },
      "Pagination": {
        "type": "object",
        "properties": {
          "total": {
            "type": "integer",
            "description": "Total number of results",
            "example": 25
          },
          "limit": {
            "type": "integer",
            "description": "Number of results per page",
            "example": 50
          },
          "offset": {
            "type": "integer",
            "description": "Number of results skipped",
            "example": 0
          },
          "hasMore": {
            "type": "boolean",
            "description": "Whether there are more results available",
            "example": false
          }
        },
        "required": [
          "total",
          "limit",
          "offset",
          "hasMore"
        ]
      },
      "AppliedFilters": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "nullable": true,
            "description": "Applied type filter",
            "example": "API"
          },
          "search": {
            "type": "string",
            "nullable": true,
            "description": "Applied search query",
            "example": null
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Applied tag filters",
            "example": []
          },
          "author": {
            "type": "string",
            "nullable": true,
            "description": "Applied author filter",
            "example": null
          },
          "license": {
            "type": "string",
            "nullable": true,
            "description": "Applied license filter",
            "example": null
          }
        }
      },
      "ResourceType": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "description": "Resource type name",
            "example": "API"
          },
          "count": {
            "type": "integer",
            "description": "Number of resources of this type",
            "example": 15
          },
          "category": {
            "type": "string",
            "description": "Category of the resource type",
            "enum": [
              "resource",
              "event"
            ],
            "example": "resource"
          }
        },
        "required": [
          "type",
          "count",
          "category"
        ]
      },
      "ResourceTypesResponse": {
        "type": "object",
        "properties": {
          "version": {
            "type": "string",
            "description": "API version",
            "example": "v1"
          },
          "types": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ResourceType"
            },
            "description": "Array of resource types with counts"
          },
          "totalTypes": {
            "type": "integer",
            "description": "Total number of resource types",
            "example": 7
          }
        },
        "required": [
          "version",
          "types",
          "totalTypes"
        ]
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "version": {
            "type": "string",
            "description": "API version",
            "example": "v1"
          },
          "error": {
            "type": "string",
            "description": "Error message",
            "example": "Internal server error"
          }
        },
        "required": [
          "version",
          "error"
        ]
      }
    }
  },
  "tags": [
    {
      "name": "Resources",
      "description": "Operations related to faith-based resources"
    }
  ]
}