openapi: 3.0.3

info:
  title: State service
  description: This service can be used to track when something started and to detect when it's no longer ongoing, or if something has been going on for too long.
  contact:
    name: Timo Savola
    url: https://savo.la
  license:
    name: BSD 3-Clause "New" or "Revised" License
  version: 0.1.0

servers:
  - url: https://state.cylinder.tube

paths:
  /{key}:
    parameters:
      - description: |
          A UUID, in lower case encoding without braces.
        name: key
        in: path
        required: true
        schema:
          type: string

    get:
      description: |
        Check the status of a key.  The response status and content depend on key retention, expiration and retirement timeouts.

        By default the retention and expiration timeouts are the same, so parameter `expire-status` has no effect unless parameter `expire` is specified.

        The inherent key retention timeout isn't fixed, but it's at least 8 days.

      parameters:
        - description: |
            Expiration timeout in seconds.  Values exceeding the inherent key retention timeout have no effect.
          name: expire
          in: query
          schema:
            $ref: "#/components/schemas/Timeout"

        - description: |
            Response status code when key exists but has expired.  Defaults to 404.
          name: expire-status
          in: query
          schema:
            $ref: "#/components/schemas/Status"

        - description: |
            Response status code when key doesn't exist.  Defaults to 404.
          name: missing-status
          in: query
          schema:
            $ref: "#/components/schemas/Status"

        - description: |
            Response status code when key exist, hasn't expired, and isn't ready for retirement.  Defaults to 200.
          name: normal-status
          in: query
          schema:
            $ref: "#/components/schemas/Status"

        - description: |
            Retirement timeout in seconds.
          name: retire
          in: query
          schema:
            $ref: "#/components/schemas/Timeout"

        - description: |
            Response status code when key exist and hasn't expired, but is ready for retirement.  Defaults to 409.
          name: retire-status
          in: query
          schema:
            $ref: "#/components/schemas/Status"

      responses:
        "200":
          description: |
            One of the following conditions is true:

            1. Parameter `missing-status` was specified as 200, and the key doesn't exist.  Response content type will be `text/plain`.
            2. Parameter `expire-status` was specified as 200, and the key exists but has expired.  Response content type will be `text/plain`.
            3. Parameter `retire-status` was specified as 200, and the key exists and hasn't expired, but it's ready for retirement.  Response content type will be `application/json`.
            4. Parameter `normal-status` was not specified or its value was 200, and the key exists and hasn't expired and isn't ready for retirement.  Response content type will be `application/json`.

            The response content is determined by the first matching condition.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Content"
            text/plain:
              schema:
                $ref: "#/components/schemas/Message"

        "204":
          description: |
            One of the following conditions is true:

            1. Parameter `missing-status` was specified as 204, and the key doesn't exist.
            2. Parameter `expire-status` was specified as 204, and the key exists but has expired.
            3. Parameter `retire-status` was specified as 204, and the key exists and hasn't expired, but it's ready for retirement.
            4. Parameter `normal-status` was specified as 204, and the key exists and hasn't expired and isn't ready for retirement.

        "400":
          description: |
            One of the following conditions is true:

            - The key isn't a properly formatted UUID.
            - A timeout argument (`retire` or `expire`) isn't an integer or is negative or too large.
            - A status argument is not one of 200, 204, 404 and 409.

        "404":
          description: |
            One of the following conditions is true:

            1. Parameter `missing-status` was not specified or its value was 404, and the key doesn't exist.  Response content type will be `text/plain`.
            2. Parameter `expire-status` was specified as 404, and the key exists but has expired.  Response content type will be `text/plain`.
            3. Parameter `retire-status` was specified as 404, and the key exists and hasn't expired, but it's ready for retirement.  Response content type will be `application/json`.
            4. Parameter `normal-status` was specified as 404, and the key exists and hasn't expired and isn't ready for retirement.  Response content type will be `application/json`.

            The response content is determined by the first matching condition.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Content"
            text/plain:
              schema:
                $ref: "#/components/schemas/Message"

        "409":
          description: |
            One of the following conditions is true:

            1. Parameter `missing-status` was specified as 409, and the key doesn't exist.  Response content type will be `text/plain`.
            2. Parameter `expire-status` was specified as 409, and the key exists but has expired.  Response content type will be `text/plain`.
            3. Parameter `retire-status` was not specified or its value was 409, and the key exists and hasn't expired, but it's ready for retirement.  Response content type will be `application/json`.
            4. Parameter `normal-status` was specified as 409, and the key exists and hasn't expired and isn't ready for retirement.  Response content type will be `application/json`.

            The response content is determined by the first matching condition.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Content"
            text/plain:
              schema:
                $ref: "#/components/schemas/Message"

    post:
      description: |
        Create or refresh a key.

        Refreshing a key keeps it from expiring and ultimately disappearing.

        The request content is ignored, but its length must not exceed 1 MB.

      parameters:
        - description: |
            A random UUID (RFC 4122 version 4), in lower case encoding without braces.
          name: key
          in: path
          required: true
          schema:
            type: string
        - description: |
            Set the key's reset time even if the key already exists.  The argument can be `now` or a timestamp.  If the timestamp is in the future, it will be replaced with current time.

            A timestamp value can be an integer (Unix time in seconds) or an RFC 3339 timestamp string (e.g. `2006-01-02T15:04:05Z`).
          name: reset
          in: query
          schema:
            type: string

      responses:
        "200":
          description: |
            Success.  The response content is empty.

        "400":
          description: |
            One of the following conditions is true:

            - The key isn't a properly formatted UUID.
            - Request content length is over 1 MB.
            - Parameter `reset` has invalid value.

        "403":
          description: |
            UUID variant isn't RFC 4122 or version isn't 4.

        "411":
          description: |
            Request header didn't specify content length.

    delete:
      description: |
        Delete a key if it exists.

        Deleting a nonexistent key doesn't result in an error.

      responses:
        "200":
          description: |
            The key no longer exists.

        "400":
          description: |
            The key isn't a properly formatted UUID.

components:
  schemas:
    Content:
      description: |
        Latest reset and refresh timestamps.
      type: object
      properties:
        reset:
          $ref: "#/components/schemas/Timestamp"
        refresh:
          $ref: "#/components/schemas/Timestamp"

    Message:
      description: |
        Error message.
      type: string

    Status:
      description: |
        Response status code.
      type: string
      enum:
        - "200"
        - "204"
        - "404"
        - "409"

    Timeout:
      description: |
        Non-negative number of seconds.
      type: integer
      format: int32

    Timestamp:
      description: |
        Date and time in UTC using RFC 3339 format.

        Example: `2006-01-02T15:04:05Z`
      type: string