openapi: 3.1.0
info:
  title: Dehradun Tourism Public REST API (dehradun1.vercel.app)
  description: Comprehensive REST API for Dehradun tourism, destinations, cultural heritage, nature spots, spiritual landmarks, and real-time visitor metrics. Hosted on Vercel with RateLimit headers, URI path versioning (/v1/), and strict deprecation policies.
  version: 1.0.0
  x-api-version: 1.0.0
  x-versioning-policy:
    type: URI Path Versioning
    current_version: v1
    supported_versions:
      - v1
    deprecation_policy_url: https://dehradun1.vercel.app/deprecation
    sunset_timeline_months: 12
    headers:
      - Deprecation
      - Sunset
      - Link
      - API-Version
  x-deprecation-policy:
    policy: 12-month minimum notice before any version sunset
    notice_method: Sunset and Deprecation HTTP headers and Link header rel=deprecation
    documentation: https://dehradun1.vercel.app/deprecation
  termsOfService: https://dehradun1.vercel.app/privacy
  contact:
    name: Akash Priyadarshi
    url: https://github.com/AkashPriyadarshii/dehraduntourism
    email: contact@dehradun1.vercel.app
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
servers:
  - url: https://dehradun1.vercel.app/api/v1
    description: Production API v1 Endpoint
  - url: https://dehradun1.vercel.app/api
    description: Production Root Endpoint
  - url: https://dehradun1.vercel.app
    description: Base Server URL
tags:
  - name: Tourism Places
    description: Attractions, temples, natural spots, and heritage sites in Dehradun
  - name: Discovery
    description: API metadata, documentation, and directory
  - name: Analytics
    description: Visitor view metrics and traffic counter
  - name: Governance
    description: API versioning, lifecycle, and deprecation policies
paths:
  /api/v1:
    get:
      tags:
        - Discovery
      summary: API Root & Service Discovery
      description: Returns metadata about available API endpoints, versioning policy, documentation URLs, and service status.
      operationId: getApiRoot
      responses:
        "200":
          description: API root directory and operational metadata
          headers:
            RateLimit-Limit:
              schema:
                type: integer
                example: 100
            RateLimit-Remaining:
              schema:
                type: integer
                example: 99
            RateLimit-Reset:
              schema:
                type: integer
                example: 60
            API-Version:
              schema:
                type: string
                example: 1.0.0
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiDirectoryResponse"
  /api/v1/places:
    get:
      tags:
        - Tourism Places
      summary: List and filter tourist attractions in Dehradun
      description: Retrieve a list of tourist destinations, historic landmarks, nature reserves, and monasteries in Dehradun with optional filtering by category or text search.
      operationId: listPlaces
      parameters:
        - name: category
          in: query
          required: false
          description: Filter places by destination category type
          schema:
            type: string
            enum: [nature, heritage, spiritual, institutional, recreation]
        - name: search
          in: query
          required: false
          description: Search keyword matching place name, description, or Hindi title
          schema:
            type: string
        - name: limit
          in: query
          required: false
          description: Maximum number of places to return (1-100)
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 50
        - name: offset
          in: query
          required: false
          description: Pagination offset
          schema:
            type: integer
            minimum: 0
            default: 0
      responses:
        "200":
          description: Successfully retrieved list of places
          headers:
            RateLimit-Limit:
              schema:
                type: integer
                example: 100
            RateLimit-Remaining:
              schema:
                type: integer
                example: 99
            RateLimit-Reset:
              schema:
                type: integer
                example: 60
            API-Version:
              schema:
                type: string
                example: 1.0.0
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PlacesListResponse"
        "400":
          description: Invalid query parameters supplied
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /api/v1/places/{id}:
    get:
      tags:
        - Tourism Places
      summary: Get specific place details by ID or slug
      description: Fetch detailed information for a single attraction in Dehradun by its slug (e.g., 'robbers-cave-guchhupani') or numeric index.
      operationId: getPlaceById
      parameters:
        - name: id
          in: path
          required: true
          description: The unique slug or index of the tourist place
          schema:
            type: string
      responses:
        "200":
          description: Place details found
          headers:
            RateLimit-Limit:
              schema:
                type: integer
                example: 100
            RateLimit-Remaining:
              schema:
                type: integer
                example: 99
            API-Version:
              schema:
                type: string
                example: 1.0.0
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PlaceDetailResponse"
        "404":
          description: Place not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /api/v1/views:
    get:
      tags:
        - Analytics
      summary: Get site visitor traffic count
      description: Retrieve the current visitor count metrics. Pass ?action=up to increment the count.
      operationId: getViews
      parameters:
        - name: action
          in: query
          required: false
          description: Set to 'up' or 'increment' to record a new page view
          schema:
            type: string
            enum: [up, increment]
      responses:
        "200":
          description: Current view count status
          headers:
            RateLimit-Limit:
              schema:
                type: integer
                example: 100
            RateLimit-Remaining:
              schema:
                type: integer
                example: 99
            API-Version:
              schema:
                type: string
                example: 1.0.0
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ViewCountResponse"
    post:
      tags:
        - Analytics
      summary: Increment visitor count
      description: Increment the visitor counter via standard POST request.
      operationId: incrementViews
      requestBody:
        description: Optional metadata payload for incrementing views
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/IncrementViewsRequest"
      responses:
        "200":
          description: View count successfully incremented
          headers:
            RateLimit-Limit:
              schema:
                type: integer
                example: 100
            RateLimit-Remaining:
              schema:
                type: integer
                example: 99
            API-Version:
              schema:
                type: string
                example: 1.0.0
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ViewCountResponse"
  /api/v1/deprecation:
    get:
      tags:
        - Governance
      summary: Get API Versioning & Deprecation Policy
      description: Retrieve the official versioning lifecycle, deprecation timeline guarantees, and HTTP header specifications for the Dehradun Tourism REST API.
      operationId: getDeprecationPolicy
      responses:
        "200":
          description: API Versioning and Deprecation policy details
          headers:
            RateLimit-Limit:
              schema:
                type: integer
                example: 100
            RateLimit-Remaining:
              schema:
                type: integer
                example: 99
            API-Version:
              schema:
                type: string
                example: 1.0.0
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DeprecationPolicyResponse"
components:
  schemas:
    Place:
      type: object
      required:
        - id
        - index
        - name
        - hindi
        - description
        - category
        - distance
        - entryFee
        - bestTime
        - lat
        - lng
        - image
      properties:
        id:
          type: string
          description: URL-friendly unique slug for the place
          example: robbers-cave-guchhupani
        index:
          type: integer
          description: 1-based order index
          example: 1
        name:
          type: string
          description: English name of the destination
          example: Robber's Cave (Guchhupani)
        hindi:
          type: string
          description: Hindi name in Devanagari script
          example: गुच्चुपानी
        description:
          type: string
          description: Detailed background, historical significance, and highlights
          example: A 600m long natural river cave formation with a waterfall.
        distance:
          type: string
          description: Approximate distance from Dehradun city center
          example: 8 km from city center
        entryFee:
          type: string
          description: Entry fee pricing or free access
          example: ₹25–50
        bestTime:
          type: string
          description: Recommended season to visit
          example: Summer
        category:
          type: string
          description: Category of the attraction
          enum: [nature, heritage, spiritual, institutional, recreation]
          example: nature
        lat:
          type: number
          format: double
          description: Geographical latitude coordinate
          example: 30.3756
        lng:
          type: number
          format: double
          description: Geographical longitude coordinate
          example: 78.0563
        image:
          type: string
          format: uri
          description: Optimized photo URL
          example: https://upload.wikimedia.org/wikipedia/commons/2/2e/Robber%27s_Cave_Dehradun.jpg
    PlacesListResponse:
      type: object
      required:
        - total
        - count
        - offset
        - limit
        - places
      properties:
        total:
          type: integer
          description: Total number of places matching criteria
          example: 17
        count:
          type: integer
          description: Number of places returned in current page
          example: 17
        offset:
          type: integer
          description: Current pagination offset
          example: 0
        limit:
          type: integer
          description: Requested limit per page
          example: 50
        places:
          type: array
          description: Array of place objects matching query
          items:
            $ref: "#/components/schemas/Place"
    PlaceDetailResponse:
      type: object
      required:
        - place
      properties:
        place:
          $ref: "#/components/schemas/Place"
    ViewCountResponse:
      type: object
      required:
        - count
        - action
        - timestamp
      properties:
        count:
          type: integer
          description: Total page view count
          example: 2080
        action:
          type: string
          description: Action performed ('read' or 'incremented')
          example: read
        timestamp:
          type: string
          format: date-time
          example: 2026-08-28T10:00:00.000Z
    IncrementViewsRequest:
      type: object
      properties:
        source:
          type: string
          description: Optional referrer or client source name
          example: ai-agent
    DeprecationPolicyResponse:
      type: object
      required:
        - api_name
        - api_version
        - active_version
        - status
        - versioning_type
        - deprecation_state
        - deprecation_policy
        - migration_guide
      properties:
        api_name:
          type: string
          example: Dehradun Tourism Public REST API (dehradun1.vercel.app)
        api_version:
          type: string
          example: 1.0.0
        active_version:
          type: string
          example: v1
        status:
          type: string
          example: supported
        versioning_type:
          type: string
          example: URI Path Versioning (/api/v1/*)
        deprecation_state:
          type: object
          required:
            - is_deprecated
            - sunset_date
            - sunset_header_value
          properties:
            is_deprecated:
              type: boolean
              example: false
            sunset_date:
              type: string
              example: 2030-12-31T23:59:59.000Z
            sunset_header_value:
              type: string
              example: Wed, 31 Dec 2030 23:59:59 GMT
        deprecation_policy:
          type: object
          required:
            - timeline_notice_months
            - policy_url
            - signaling_headers
          properties:
            timeline_notice_months:
              type: integer
              example: 12
            policy_url:
              type: string
              example: https://dehradun1.vercel.app/deprecation
            signaling_headers:
              type: array
              items:
                type: string
        migration_guide:
          type: string
          example: No breaking changes currently scheduled.
    ApiEndpointsMap:
      type: object
      required:
        - root
        - places
        - place_by_id
        - views
        - deprecation
      properties:
        root:
          type: string
          example: /api/v1
        places:
          type: string
          example: /api/v1/places
        place_by_id:
          type: string
          example: /api/v1/places/{id}
        views:
          type: string
          example: /api/v1/views
        deprecation:
          type: string
          example: /api/v1/deprecation
    VersioningPolicy:
      type: object
      required:
        - current_version
        - lifecycle
        - deprecation_policy
      properties:
        current_version:
          type: string
          example: v1
        lifecycle:
          type: string
          example: Active supported version
        deprecation_policy:
          type: string
          example: Sunset notice provided 12 months in advance via Sunset HTTP headers.
    ApiDirectoryResponse:
      type: object
      required:
        - name
        - description
        - version
        - status
        - versioning_policy
        - documentation_url
        - developer_portal
        - openapi_url
        - openapi_yaml_url
        - mcp_server
        - llms_txt
        - endpoints
      properties:
        name:
          type: string
          example: Dehradun Tourism Public REST API (dehradun1.vercel.app)
        description:
          type: string
          example: Official public developer API providing tourism data for Dehradun.
        version:
          type: string
          example: 1.0.0
        status:
          type: string
          example: operational
        versioning_policy:
          $ref: "#/components/schemas/VersioningPolicy"
        documentation_url:
          type: string
          format: uri
          example: https://dehradun1.vercel.app/docs/api
        developer_portal:
          type: string
          format: uri
          example: https://dehradun1.vercel.app/developers
        openapi_url:
          type: string
          format: uri
          example: https://dehradun1.vercel.app/openapi.json
        openapi_yaml_url:
          type: string
          format: uri
          example: https://dehradun1.vercel.app/openapi.yaml
        mcp_server:
          type: string
          format: uri
          example: https://dehradun1.vercel.app/.well-known/mcp
        llms_txt:
          type: string
          format: uri
          example: https://dehradun1.vercel.app/llms.txt
        endpoints:
          $ref: "#/components/schemas/ApiEndpointsMap"
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          $ref: "#/components/schemas/ErrorDetail"
    ErrorDetail:
      type: object
      required:
        - code
        - message
        - status
        - hint
      properties:
        code:
          type: string
          description: Standard machine-readable error code
          example: PLACE_NOT_FOUND
        message:
          type: string
          description: Human-readable error description
          example: Tourist attraction with ID 'unknown-place' was not found.
        status:
          type: integer
          description: HTTP status code
          example: 404
        hint:
          type: string
          description: Actionable guidance to resolve the error
          example: Query GET /api/v1/places for a full list of valid places.
