Dropto Health API

openapi: 3.2.0
info:
  title: Drop2Run.Api | v1 Health API
  version: 1.0.0
  description: 'Liveness for the control plane, and the endpoint the browser reports its own errors to. Nothing here needs a credential, and nothing here touches a site: the data plane serves files whether or not these answer.'
servers:
- description: Production
  url: https://dropto.run
tags:
- description: 'Liveness for the control plane, and the endpoint the browser reports its own errors to. Nothing here needs a credential, and nothing here touches a site: the data plane serves files whether or not these answer.'
  name: Health
paths:
  /api/health:
    get:
      operationId: Health
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthResponse'
          description: OK
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthResponse'
          description: Service Unavailable
      summary: Checks the API and its database connection
      tags:
      - Health
  /api/health/client:
    get:
      operationId: ClientAddress
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientAddressResponse'
          description: OK
      summary: Reports the client address the API resolved, for checking the proxy hop count
      tags:
      - Health
components:
  schemas:
    ClientAddressResponse:
      description: Response of the client-address probe.
      properties:
        address:
          description: The address the API will rate-limit this caller by.
          type: string
        clientIpHeader:
          description: 'Header the address was taken from. `X-Forwarded-For` means the chain was walked and

            TrustedHops is what decided the answer; any other name means that header was read

            directly and the hop count did not apply.'
          type: string
        trustedHops:
          description: Configured number of proxies in front of the API.
          format: int32
          pattern: ^-?(?:0|[1-9]\d*)$
          type:
          - integer
          - string
      required:
      - address
      - trustedHops
      - clientIpHeader
      type: object
    HealthResponse:
      description: Health check response.
      properties:
        database:
          description: 'Postgres connectivity: `up` or `down`.'
          type: string
        status:
          description: 'Overall status: `ok` or `degraded`.'
          type: string
      required:
      - status
      - database
      type: object
  securitySchemes:
    accessToken:
      description: 'A personal access token, created at /account/tokens. Sent as `Authorization: Bearer d2r_...`. A rejected token answers 401 with `invalid_token`, which is deliberately distinct from the 403 a valid credential gets for something it may not do.'
      scheme: bearer
      type: http
    claimToken:
      description: Returned once when an anonymous site is created, and the only credential that site has until somebody signs in and claims it.
      in: header
      name: X-Claim-Token
      type: apiKey
    session:
      description: The browser session, set by signing in with Google. HttpOnly, so a script cannot read it and a client outside a browser cannot send it.
      in: cookie
      name: d2r_session
      type: apiKey