openapi.yaml

openapi: 3.0.3

info:
  title: Shrtn API
  version: 0.8.0
  description: |
    REST API for the Shrtn browser extension.

    Shrtn validates HTTP and HTTPS URLs, generates unique
    seven-character short codes, stores links persistently in
    PostgreSQL, redirects public short URLs, and exposes click analytics.

servers:
  - url: https://shrtn.up.railway.app
    description: Production Railway server

  - url: http://localhost:5056
    description: Local development server

tags:
  - name: Health
    description: Service availability endpoints

  - name: Links
    description: Short-link creation and redirect endpoints

  - name: Analytics
    description: Short-link click analytics endpoints

paths:
  /health:
    get:
      tags:
        - Health
      summary: Get API health
      operationId: getHealth
      responses:
        "200":
          description: The Shrtn API is running
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HealthResponse"
              example:
                status: UP
                service: shrtn-api
                version: 0.8.0
                timestamp: "2026-07-15T02:25:00.000Z"

  /api/v1/links:
    post:
      tags:
        - Links
      summary: Create a shortened URL
      description: |
        Validates an HTTP or HTTPS URL, generates a unique
        seven-character short code, and stores the link persistently
        in PostgreSQL.
      operationId: createShortLink
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateLinkRequest"
            examples:
              standardUrl:
                summary: Standard HTTPS URL
                value:
                  originalUrl: https://example.com/products?id=123

              localDevelopmentUrl:
                summary: Local development URL
                value:
                  originalUrl: http://localhost:5173

      responses:
        "201":
          description: Short link created successfully
          headers:
            Location:
              description: Complete shortened URL
              schema:
                type: string
                format: uri
              example: https://shrtn.up.railway.app/AbC123x
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LinkResponse"
              example:
                data:
                  originalUrl: https://example.com/products?id=123
                  shortCode: AbC123x
                  shortUrl: https://shrtn.up.railway.app/AbC123x
                  createdAt: "2026-07-15T02:25:00.000Z"

        "400":
          description: Request validation or JSON parsing failed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                requiredUrl:
                  summary: Missing URL
                  value:
                    error:
                      code: VALIDATION_ERROR
                      message: Request validation failed.
                      details:
                        - field: originalUrl
                          message: originalUrl is required.

                invalidUrl:
                  summary: Invalid URL
                  value:
                    error:
                      code: VALIDATION_ERROR
                      message: Request validation failed.
                      details:
                        - field: originalUrl
                          message: originalUrl must be a valid URL.

                unsupportedProtocol:
                  summary: Unsupported URL protocol
                  value:
                    error:
                      code: VALIDATION_ERROR
                      message: Request validation failed.
                      details:
                        - field: originalUrl
                          message: Only HTTP and HTTPS URLs are supported.

                invalidJson:
                  summary: Malformed JSON
                  value:
                    error:
                      code: INVALID_JSON
                      message: The request body contains invalid JSON.

        "409":
          description: A unique short code could not be generated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error:
                  code: SHORT_CODE_CONFLICT
                  message: A unique short code could not be generated.

        "413":
          description: Request body exceeds the 10 KB limit
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error:
                  code: REQUEST_TOO_LARGE
                  message: The request body is too large.

        "429":
          description: The client exceeded the request rate limit
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error:
                  code: RATE_LIMIT_EXCEEDED
                  message: Too many requests. Please try again later.

        "500":
          description: Unexpected server failure
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error:
                  code: INTERNAL_SERVER_ERROR
                  message: An unexpected server error occurred.

  /api/v1/links/{shortCode}/analytics:
    get:
      tags:
        - Analytics
      summary: Get analytics for a shortened link
      description: |
        Returns the stored destination, creation timestamp, total
        redirect count, and most recent redirect timestamp.

        Reading analytics does not increment the click count.
      operationId: getLinkAnalytics
      parameters:
        - $ref: "#/components/parameters/ShortCode"

      responses:
        "200":
          description: Link analytics retrieved successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LinkAnalyticsResponse"
              example:
                data:
                  originalUrl: https://example.com/products?id=123
                  shortCode: AbC123x
                  createdAt: "2026-07-15T02:25:00.000Z"
                  clickCount: 3
                  lastClickedAt: "2026-07-15T03:10:00.000Z"

        "404":
          description: The short link does not exist or the route format is invalid
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                linkNotFound:
                  summary: Valid code with no stored record
                  value:
                    error:
                      code: LINK_NOT_FOUND
                      message: The requested short link does not exist.

                invalidCodeFormat:
                  summary: Invalid short-code format
                  value:
                    error:
                      code: ROUTE_NOT_FOUND
                      message: Route GET /api/v1/links/not-valid/analytics does not exist.

        "429":
          description: The client exceeded the request rate limit
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error:
                  code: RATE_LIMIT_EXCEEDED
                  message: Too many requests. Please try again later.

        "500":
          description: Unexpected server failure
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error:
                  code: INTERNAL_SERVER_ERROR
                  message: An unexpected server error occurred.

  /{shortCode}:
    get:
      tags:
        - Links
      summary: Redirect a short link
      description: |
        Finds a persistent PostgreSQL link using its seven-character
        short code, atomically records the redirect analytics, and
        redirects the client to the original URL.
      operationId: redirectShortLink
      parameters:
        - $ref: "#/components/parameters/ShortCode"

      responses:
        "302":
          description: Redirect to the original URL
          headers:
            Location:
              description: Original URL associated with the short code
              schema:
                type: string
                format: uri
              example: https://example.com/products?id=123

        "404":
          description: The short link does not exist or the route format is invalid
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                linkNotFound:
                  summary: Valid code with no stored record
                  value:
                    error:
                      code: LINK_NOT_FOUND
                      message: The requested short link does not exist.

                invalidCodeFormat:
                  summary: Invalid short-code format
                  value:
                    error:
                      code: ROUTE_NOT_FOUND
                      message: Route GET /not-valid does not exist.

        "429":
          description: The client exceeded the request rate limit
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error:
                  code: RATE_LIMIT_EXCEEDED
                  message: Too many requests. Please try again later.

        "500":
          description: Unexpected server failure
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error:
                  code: INTERNAL_SERVER_ERROR
                  message: An unexpected server error occurred.

components:
  parameters:
    ShortCode:
      name: shortCode
      in: path
      required: true
      description: Seven-character alphanumeric Shrtn code
      schema:
        type: string
        minLength: 7
        maxLength: 7
        pattern: "^[A-Za-z0-9]{7}$"
        example: AbC123x

  schemas:
    HealthResponse:
      type: object
      additionalProperties: false
      required:
        - status
        - service
        - version
        - timestamp
      properties:
        status:
          type: string
          enum:
            - UP
          example: UP

        service:
          type: string
          enum:
            - shrtn-api
          example: shrtn-api

        version:
          type: string
          example: 0.8.0

        timestamp:
          type: string
          format: date-time
          example: "2026-07-15T02:25:00.000Z"

    CreateLinkRequest:
      type: object
      additionalProperties: false
      required:
        - originalUrl
      properties:
        originalUrl:
          type: string
          format: uri
          minLength: 1
          maxLength: 4096
          description: HTTP or HTTPS URL to shorten
          example: https://example.com/products?id=123

    Link:
      type: object
      additionalProperties: false
      required:
        - originalUrl
        - shortCode
        - shortUrl
        - createdAt
      properties:
        originalUrl:
          type: string
          format: uri
          example: https://example.com/products?id=123

        shortCode:
          type: string
          minLength: 7
          maxLength: 7
          pattern: "^[A-Za-z0-9]{7}$"
          example: AbC123x

        shortUrl:
          type: string
          format: uri
          example: https://shrtn.up.railway.app/AbC123x

        createdAt:
          type: string
          format: date-time
          example: "2026-07-15T02:25:00.000Z"

    LinkResponse:
      type: object
      additionalProperties: false
      required:
        - data
      properties:
        data:
          $ref: "#/components/schemas/Link"

    LinkAnalytics:
      type: object
      additionalProperties: false
      required:
        - originalUrl
        - shortCode
        - createdAt
        - clickCount
        - lastClickedAt
      properties:
        originalUrl:
          type: string
          format: uri
          example: https://example.com/products?id=123

        shortCode:
          type: string
          minLength: 7
          maxLength: 7
          pattern: "^[A-Za-z0-9]{7}$"
          example: AbC123x

        createdAt:
          type: string
          format: date-time
          example: "2026-07-15T02:25:00.000Z"

        clickCount:
          type: integer
          format: int64
          minimum: 0
          example: 3

        lastClickedAt:
          type: string
          format: date-time
          nullable: true
          example: "2026-07-15T03:10:00.000Z"

    LinkAnalyticsResponse:
      type: object
      additionalProperties: false
      required:
        - data
      properties:
        data:
          $ref: "#/components/schemas/LinkAnalytics"

    ErrorDetail:
      type: object
      additionalProperties: false
      required:
        - field
        - message
      properties:
        field:
          type: string
          example: originalUrl

        message:
          type: string
          example: originalUrl must be a valid URL.

    Error:
      type: object
      additionalProperties: false
      required:
        - code
        - message
      properties:
        code:
          type: string
          example: VALIDATION_ERROR

        message:
          type: string
          example: Request validation failed.

        details:
          type: array
          items:
            $ref: "#/components/schemas/ErrorDetail"

    ErrorResponse:
      type: object
      additionalProperties: false
      required:
        - error
      properties:
        error:
          $ref: "#/components/schemas/Error"