# Proposed contract, version 1: endpoints, errors, paging, idempotency, security and the capability of every
# operation. Resource schemas were initialized from the data model (docs/06-data) and are kept aligned with it; input
# schemas (*Input, *Request) and views are specific to this contract. Status: proposal for review, not confirmed design.
# Conventions: docs/05-interfaces/choosing-an-interface.md. Vendor extensions: x-moonitoring-audience (who calls),
# x-moonitoring-capability (the capability checked), x-moonitoring-entitlement (the entitlement feature checked),
# x-moonitoring-requirements (the requirements of 1.requisiti-raffinati.txt the operation serves).
openapi: 3.1.0
info:
  title: Releases Downloads API
  version: 1.0.0
  description: 'Download links of the installer of every application (decided 2026-11-11): a universal latest link
    that detects the platform, a latest link per platform and a link per version and platform. They are open to anyone
    whatever the application''s audience, the one exception to the rule that nothing private can be enumerated: a link
    names the application and a version label, never a build number, and the installer carries no secret. Every answer
    is a redirect to a short-lived signed URL of the CDN, in prod and in stage (decided 2026-11-11), never a listing of what the caller may not receive, and
    records an anonymous download event.'
servers:
- url: https://releases.moonitoring.com/downloads/v1
  description: Prod, without authentication; rate limited by Cloud Armor at the load balancer
- url: https://stage-releases.moonitoring.com/downloads/v1
  description: Stage, through IAP like every client path
security:
- {}
tags:
- name: Links
  description: Download links of installers
paths:
  /{application_slug}/latest:
    get:
      summary: Download the latest installer for this computer
      operationId: getLatestDownload
      description: 'The universal latest link. Detects the operating system and architecture from the User-Agent and
        the client hints `Sec-CH-UA-Platform` and `Sec-CH-UA-Arch` (the first answer asks for them with `Accept-CH`),
        and redirects to the installer of that platform for the active release of the application''s default channel
        (req 101.10). When it cannot tell the platform, or the latest build has no installer for it, it answers a small
        HTML page that links the latest link of every platform the build has an installer for. Records a download event
        when it redirects.'
      tags:
      - Links
      parameters:
      - $ref: '#/components/parameters/ApplicationSlug'
      responses:
        '302':
          $ref: '#/components/responses/InstallerRedirect'
        '200':
          description: The platforms of the latest build, when the platform could not be told.
          content:
            text/html:
              schema:
                type: string
        '404':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/NotFound
        '429':
          $ref: '#/components/responses/TooManyRequests'
      x-moonitoring-audience: public
      x-moonitoring-capability: null
      x-moonitoring-requirements:
      - '101.10'
      - '151'
      - '119'
  /{application_slug}/latest/{platform}:
    get:
      summary: Download the latest installer for a platform
      operationId: getLatestPlatformDownload
      description: Redirects to the installer of that platform for the active release of the application's default
        channel. 404 when the application has no default channel, the channel no active release, or the build no
        installer for the platform. Records a download event.
      tags:
      - Links
      parameters:
      - $ref: '#/components/parameters/ApplicationSlug'
      - $ref: '#/components/parameters/Platform'
      responses:
        '302':
          $ref: '#/components/responses/InstallerRedirect'
        '404':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/NotFound
        '429':
          $ref: '#/components/responses/TooManyRequests'
      x-moonitoring-audience: public
      x-moonitoring-capability: null
      x-moonitoring-requirements:
      - '101.10'
      - '151'
      - '119'
  /{application_slug}/versions/{version_label}/{platform}:
    get:
      summary: Download the installer of a version for a platform
      operationId: getVersionDownload
      description: 'Redirects to the installer of the ready build of the application with this version label, for
        that platform; a revoked build or an unknown label answers 404. The installer installs that version only while
        a channel the person may receive still names it in its current targets; otherwise it says that the version is
        no longer offered and offers the latest. Records a download event.'
      tags:
      - Links
      parameters:
      - $ref: '#/components/parameters/ApplicationSlug'
      - name: version_label
        in: path
        required: true
        schema:
          type: string
        description: The version label of the build (req 109.4), e.g. 2.4.2.
      - $ref: '#/components/parameters/Platform'
      responses:
        '302':
          $ref: '#/components/responses/InstallerRedirect'
        '404':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/NotFound
        '429':
          $ref: '#/components/responses/TooManyRequests'
      x-moonitoring-audience: public
      x-moonitoring-capability: null
      x-moonitoring-requirements:
      - '109.4'
      - '151'
      - '119'
components:
  parameters:
    ApplicationSlug:
      name: application_slug
      in: path
      required: true
      schema:
        type: string
      description: The application's slug (req 101.3), e.g. farm-sync-client.
    Platform:
      name: platform
      in: path
      required: true
      schema:
        type: string
        pattern: ^(windows|macos|linux|android|ios)-(x64|arm64|universal)$
      description: The platform as `<os>-<arch>` of the ReleasePlatform (req 102), e.g. windows-x64.
  responses:
    InstallerRedirect:
      description: 'A redirect to the installer file: a signed URL of the CDN valid for ten minutes, in prod and in stage. The
        file name is `<application slug>-<version label>-<platform>` with the platform''s extension. `Cache-Control:
        no-store`, since a latest link changes with each release.'
      headers:
        Location:
          schema:
            type: string
            format: uri
    TooManyRequests:
      description: The edge rate limit of the download links was reached.
      headers:
        Retry-After:
          schema:
            type: integer