Add GTFS feed availability history endpoint

[davidgamez]

Describe the problem

Expose availability history through a dedicated endpoint under the GTFS feed API. This should be a separate endpoint, as the number of checks can be large.

Proposed solution

Proposed OpenAPI schema

paths:
  /v1/gtfs_feeds/{feed_id}/availability:
    get:
      tags:
        - GTFS Feeds
      summary: Get GTFS feed availability checks
      description: >
        Returns historical availability checks for a GTFS feed. Availability is
        based on scheduled lightweight HTTP checks against the feed URL, such as
        HEAD requests or ranged GET requests. This endpoint does not download or
        validate the full GTFS dataset.

        Results are always ordered by checked_at from oldest to newest.
      operationId: getGtfsFeedAvailability
      parameters:
        - name: feed_id
          in: path
          required: true
          description: Unique identifier of the GTFS feed.
          schema:
            type: string
          example: mdb-123

        - name: from
          in: query
          required: false
          description: Return availability checks performed at or after this timestamp.
          schema:
            type: string
            format: date-time
          example: "2026-04-01T00:00:00Z"

        - name: to
          in: query
          required: false
          description: Return availability checks performed at or before this timestamp.
          schema:
            type: string
            format: date-time
          example: "2026-05-01T00:00:00Z"

      responses:
        "200":
          description: Availability history for the GTFS feed, ordered by checked_at from oldest to newest.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GtfsFeedAvailabilityResponse"
              example:
                feed_id: mdb-123
                checks:
                  - checked_at: "2026-05-12T10:00:00Z"
                    success: true
                    request_method: GET
                    status_code: 206
                    latency_ms: 920.5
                    error_type: null
                  - checked_at: "2026-05-13T10:00:00Z"
                    success: false
                    request_method: HEAD
                    status_code: 404
                    latency_ms: 312.1
                    error_type: null
                  - checked_at: "2026-05-14T10:00:00Z"
                    success: true
                    request_method: HEAD
                    status_code: 200
                    latency_ms: 845.3
                    error_type: null

        "400":
          description: Invalid request parameters.

        "404":
          description: GTFS feed not found.

        "500":
          description: Internal server error.

components:
  schemas:
    GtfsFeedAvailabilityResponse:
      type: object
      required:
        - feed_id
        - checks
      properties:
        feed_id:
          type: string
          description: Unique identifier of the GTFS feed.
          example: mdb-123

        checks:
          type: array
          description: >
            Availability checks matching the requested filters, ordered by
            checked_at from oldest to newest.
          items:
            $ref: "#/components/schemas/GtfsFeedAvailabilityCheck"

    GtfsFeedAvailabilityCheck:
      type: object
      required:
        - checked_at
        - success
        - request_method
      properties:
        checked_at:
          type: string
          format: date-time
          description: Timestamp when the availability check was performed.
          example: "2026-05-14T10:00:00Z"

        success:
          type: boolean
          description: Whether the feed URL was reachable using the lightweight check.
          example: true

        request_method:
          type: string
          description: HTTP method used for the availability check.
          enum:
            - HEAD
            - GET
          example: HEAD

        status_code:
          type: integer
          nullable: true
          description: Final HTTP status code returned by the feed URL, when available.
          example: 200

        latency_ms:
          type: number
          format: double
          nullable: true
          description: Time taken to receive the response, in milliseconds.
          example: 845.3

        error_type:
          type: string
          nullable: true
          description: Machine-readable error category when the check failed.
          example: timeout

Alternatives you've considered

No response

Additional context

No response