openapi: 3.0.3
info:
  title: TimedURL Public API
  version: 0.1.1
  description: Public API for creating and managing time-limited URLs with API keys.
servers:
- url: https://api.timedurl.com/v1
  description: Production API Server
- url: https://api-gw-dev.timedurl.com/v1
  description: Staging API Server
paths:
  /timed-urls:
    get:
      summary: List all timed URLs
      x-openapi-router-controller: timedurl.api.external_api.handlers
      operationId: list_timed_urls
      parameters:
      - name: limit
        in: query
        description: Number of items to return (max 1000)
        required: false
        schema:
          type: integer
          default: 100
          minimum: 1
          maximum: 1000
      - name: offset
        in: query
        description: Number of items to skip before starting to collect the result
          set
        required: false
        schema:
          type: integer
          default: 0
          minimum: 0
      tags:
      - Timed URLs
      security:
      - ApiKeyAuth: []
      responses:
        200:
          description: A list of timed URLs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedTimedURLList'
        401:
          $ref: '#/components/responses/UnauthorizedError'
    post:
      summary: Create a new timed URL
      x-openapi-router-controller: timedurl.api.external_api.handlers
      operationId: create_timed_url
      tags:
      - Timed URLs
      security:
      - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            example:
              destination_url: https://www.example.com
              expiry_time: '2024-09-20T15:00:00Z'
            schema:
              $ref: '#/components/schemas/TimedURLCreationRequest'
      responses:
        201:
          description: Timed URL successfully created
          content:
            application/json:
              example:
                destination_url: https://www.example.com
                expiry_url: https://www.example.com
                expiry_time: '2024-09-20T15:00:00Z'
                created_at: '2024-09-20T12:00:00Z'
                updated_at: '2024-09-20T12:00:00Z'
                redirect_count: 0
              schema:
                $ref: '#/components/schemas/TimedURLCreationResponse'
        401:
          $ref: '#/components/responses/UnauthorizedError'
  /timed-urls/{url_key}:
    get:
      summary: Get a specific timed URL
      x-openapi-router-controller: timedurl.api.external_api.handlers
      operationId: get_timed_url
      tags:
      - Timed URLs
      security:
      - ApiKeyAuth: []
      parameters:
      - name: url_key
        in: path
        required: true
        schema:
          type: string
        description: The ID of the timed URL.
      responses:
        200:
          description: A single timed URL
          content:
            application/json:
              example:
                destination_url: https://www.example.com
                expiry_url: https://www.example.com
                expiry_time: '2024-09-20T15:00:00Z'
                created_at: '2024-09-20T12:00:00Z'
                redirect_count: 3
              schema:
                $ref: '#/components/schemas/TimedURLGetResponse'
        401:
          $ref: '#/components/responses/UnauthorizedError'
        404:
          description: Timed URL not found
    put:
      summary: Update a timed URL
      x-openapi-router-controller: timedurl.api.external_api.handlers
      operationId: update_timed_url
      tags:
      - Timed URLs
      security:
      - ApiKeyAuth: []
      parameters:
      - name: url_key
        in: path
        required: true
        schema:
          type: string
        description: The ID of the timed URL.
      requestBody:
        required: true
        content:
          application/json:
            example:
              destination_url: https://www.example.com
              expiry_time: '2024-09-20T15:00:00Z'
            schema:
              allOf:
              - $ref: '#/components/schemas/BaseTimedURLRequest'
      responses:
        200:
          description: Timed URL updated
          content:
            application/json:
              example:
                destination_url: https://www.example.com
                expiry_url: https://www.example.com
                expiry_time: '2024-09-20T15:00:00Z'
                created_at: '2024-09-20T12:00:00Z'
                redirect_count: 3
              schema:
                $ref: '#/components/schemas/TimedURLGetResponse'
        401:
          $ref: '#/components/responses/UnauthorizedError'
        404:
          description: Timed URL not found
    delete:
      summary: Delete a timed URL
      x-openapi-router-controller: timedurl.api.external_api.handlers
      operationId: delete_timed_url
      tags:
      - Timed URLs
      security:
      - ApiKeyAuth: []
      parameters:
      - name: url_key
        in: path
        required: true
        schema:
          type: string
        description: The ID of the timed URL.
      responses:
        204:
          description: Timed URL successfully deleted
        401:
          $ref: '#/components/responses/UnauthorizedError'
        404:
          description: Timed URL not found
components:
  schemas:
    BaseTimedURLRequest:
      type: object
      properties:
        suffix:
          type: string
          description: Custom suffix appended to timedurl, Must be an alphanumeric
            string containing only letters (A-Z, a-z) and numbers (0-9), with no spaces
            or special characters.
          example: abcdefg
          maxLength: 7
          minLength: 3
          pattern: ^[a-zA-Z0-9]+$
        destination_url:
          type: string
          format: uri
          description: The target URL to redirect to.
          example: https://www.example.com
        expiry_time:
          type: string
          description: Specific date and time when the URL will expire.
          example: '2024-12-31T23:59:59Z'
        fallback_destination_url:
          type: string
          nullable: true
          format: uri
          description: An alternative target URL to redirect to if validity time expired.
      additionalProperties: false
    BaseTimedURLResponse:
      type: object
      required:
      - expiry_url
      - destination_url
      - expiry_time
      properties:
        destination_url:
          type: string
          format: uri
          description: The target URL to redirect to.
          example: https://www.example.com
        expiry_url:
          type: string
          format: uri
          description: The target URL to redirect to.
          example: https://www.timedurl.com/FgakRo
        expiry_time:
          type: string
          description: Specific date and time when the URL will expire.
          example: '2024-12-31T23:59:59Z'
        fallback_destination_url:
          type: string
          nullable: true
          format: uri
          description: An alternative target URL to redirect to if validity time expired.
          example: https://www.alt-example.com
    TimedURLMetadata:
      type: object
      properties:
        created_at:
          type: string
          format: date-time
          description: Timestamp when the timed-url was created.
          example: '2024-09-20T12:00:00Z'
        updated_at:
          type: string
          format: date-time
          nullable: true
          description: Timestamp when the timed-url was created.
          example: '2024-09-20T12:00:00Z'
        has_expired:
          type: boolean
          description: True if link is not expired, False otherwise
          default: false
        redirect_count:
          type: integer
          description: Number of times the timed-url has been accessed.
          example: 5
    TimedURLCreationRequest:
      description: Fields used to create a timed URL.
      allOf:
      - $ref: '#/components/schemas/BaseTimedURLRequest'
      - type: object
        required:
        - destination_url
        - expiry_time
    TimedURLCreationResponse:
      description: A timed URL has been created.
      allOf:
      - $ref: '#/components/schemas/BaseTimedURLResponse'
    TimedURLUpdateResponse:
      description: A timed URL has been created.
      allOf:
      - $ref: '#/components/schemas/BaseTimedURLResponse'
    TimedURLGetResponse:
      description: Information about timed URL(s) has been created.
      allOf:
      - $ref: '#/components/schemas/BaseTimedURLResponse'
      - $ref: '#/components/schemas/TimedURLMetadata'
    PaginatedTimedURLList:
      type: object
      required:
      - items
      - total
      - limit
      - offset
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/TimedURLGetResponse'
        total:
          type: integer
          description: Total number of timed URLs available
        limit:
          type: integer
          description: Number of items requested
        offset:
          type: integer
          description: Number of items skipped
  responses:
    UnauthorizedError:
      description: Unauthorized access due to missing or invalid OAuth2 token.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                example: Unauthorized
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      x-apikeyInfoFunc: timedurl.api.auth_utils.api_key_info_func
security:
- ApiKeyAuth: []
