openapi: '3.0.0'
info:
  title: Decentraland Governance API
  version: '1.0.0'
servers:
  - url: localhost:4000/api
tags:
  - name: Proposals
    description: The Proposals section of the API provides endpoints to interact with proposals and grants related to the. DAO. Proposals are the format community members use to propose changes to the Decentraland ecosystem.
  - name: Coauthor
    description: The Coauthor section of the API is focused on retrieving information about the co-authors associated with a particular proposal. Co-authors are individuals or organizations who are collaborating on a proposal, and may have contributed to its creation.
  - name: Grant Updates
    description: The Grant Updates section of the API is focused on retrieving information related to updates associated with a specific approved Grant. Updates are  used to inform the community or stakeholders about the progress of a Grant project, highlighting any important milestones, challenges, or changes.
  - name: DAO Committee
    description: The DAO Committee section of the API is focused on retrieving information related to the members of the DAO Committee, individuals resnponsible for executing transactions on chain, enacting proposals and with access to the DAO Treasury.
  - name: Votes
    description: The Votes section of the API is focused on retrieving information related to the voting process associated with a specific proposal. Votes are the way community members express their support or opposition to a proposal.
  - name: Subscriptions (User Watchlist)
    description: The Subscriptions section of the API is focused on retrieving information related to the subscriptions associated with a specific proposal. This feature is called Watchlist on the Governance dApp. Watchlists are usually used to have a closer look on updates or changes related to a proposal.
  - name: Badges
    description: Endpoints related to user badges
  - name: Users
    description: These endpoints handle user validation
paths:
  /proposals:
    get:
      tags:
        - Proposals
      summary: Get proposals filtered by the given query params
      parameters:
        - name: user
          $ref: '#/components/parameters/user'
        - name: type
          $ref: '#/components/parameters/proposalType'
        - name: status
          $ref: '#/components/parameters/proposalStatus'
        - name: subscribed
          $ref: '#/components/parameters/isSubscribed'
        - name: coauthor
          $ref: '#/components/parameters/isCoauthor'
        - name: search
          $ref: '#/components/parameters/search'
        - name: timeFrame
          $ref: '#/components/parameters/timeFrame'
        - name: timeFrameKey
          $ref: '#/components/parameters/timeFrameKey'
        - name: order
          $ref: '#/components/parameters/order'
        - name: limit
          $ref: '#/components/parameters/limit'
        - name: offset
          $ref: '#/components/parameters/offset'
        - name: snapshotIds
          $ref: '#/components/parameters/snapshotIds'
      responses:
        '200':
          $ref: '#/components/responses/200'
  /proposals/grants:
    get:
      tags:
        - Proposals
      summary: Get active and past enacted grants, as well as the total number of submitted grants requests
      responses:
        '200':
          $ref: '#/components/responses/200'
  /proposals/grants/{address}:
    get:
      tags:
        - Proposals
      summary: Get active and past enacted grants from the given address
      parameters:
        - name: address
          $ref: '#/components/parameters/address'
        - name: coauthoring
          $ref: '#/components/parameters/isCoauthor'
      responses:
        '200':
          $ref: '#/components/responses/200'
  /proposals/{proposal}:
    get:
      tags:
        - Proposals
      summary: Get the proposal from the given ID
      parameters:
        - name: proposalId
          $ref: '#/components/parameters/proposalId'
      responses:
        '200':
          $ref: '#/components/responses/200'
        '404':
          $ref: '#/components/responses/404'
  /proposals/{proposal}/comments:
    get:
      tags:
        - Proposals
      summary: Get the proposal comments from the given ID
      parameters:
        - name: proposalId
          $ref: '#/components/parameters/proposalId'
      responses:
        '200':
          $ref: '#/components/responses/200'
  /proposals/linked-wearables/image:
    get:
      tags:
        - Proposals
      summary: Check if a given image is valid for linked wearables gallery
      parameters:
        - name: image URL
          $ref: '#/components/parameters/image_url'
      responses:
        '200':
          $ref: '#/components/responses/200'

  /coauthors/{proposal}:
    get:
      tags:
        - Coauthor
      summary: Get the coauthors of the given proposal ID
      parameters:
        - name: proposal
          $ref: '#/components/parameters/proposalId'
      responses:
        '200':
          $ref: '#/components/responses/200'

  /coauthors/{proposal}/{status}:
    get:
      tags:
        - Coauthor
      summary: Get the coauthors of the given proposal ID filtered by the given request status
      parameters:
        - name: proposal
          $ref: '#/components/parameters/proposalId'
        - name: status
          $ref: '#/components/parameters/coauthorStatus'
      responses:
        '200':
          $ref: '#/components/responses/200'
  /coauthors/proposals/{address}:
    get:
      tags:
        - Coauthor
      summary: Get the proposals in which the given address is a co-author
      parameters:
        - name: address
          $ref: '#/components/parameters/address'
      responses:
        '200':
          $ref: '#/components/responses/200'
  /coauthors/proposals/{address}/{status}:
    get:
      tags:
        - Coauthor
      summary: Get the proposals in which the given address is a co-author by request status
      parameters:
        - name: address
          $ref: '#/components/parameters/address'
        - name: status
          $ref: '#/components/parameters/coauthorStatus'
      responses:
        '200':
          $ref: '#/components/responses/200'
  /proposals/{proposal}/updates:
    get:
      tags:
        - Grant Updates
      summary: Get the updates from the given proposal
      parameters:
        - name: proposal
          $ref: '#/components/parameters/proposalId'
      responses:
        '200':
          $ref: '#/components/responses/200'
  /proposals/{update}/update:
    get:
      tags:
        - Grant Updates
      summary: Get the update details from the given update ID
      parameters:
        - name: update
          $ref: '#/components/parameters/updateId'
      responses:
        '200':
          $ref: '#/components/responses/200'

  /committee:
    get:
      tags:
        - DAO Committee
      summary: Get the DAO Committee members addresses
      responses:
        '200':
          $ref: '#/components/responses/200'

  /votes:
    get:
      tags:
        - Votes
      summary: Get the cached votes from the given proposal ID
      parameters:
        - name: id
          in: query
          description: Proposal ID
          required: true
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/200'
  /votes/{address}:
    get:
      tags:
        - Votes
      summary: Get the votes from a given address
      parameters:
        - name: address
          $ref: '#/components/parameters/address'
      responses:
        '200':
          $ref: '#/components/responses/200'
  /proposals/{proposal}/votes:
    get:
      tags:
        - Votes
      summary: Get the votes from a given proposal ID
      parameters:
        - name: proposal
          $ref: '#/components/parameters/proposalId'
      responses:
        '200':
          $ref: '#/components/responses/200'

  /proposals/{proposal}/subscriptions:
    get:
      tags:
        - Subscriptions (User Watchlist)
      summary: Get the subscriptions from a given proposal ID
      parameters:
        - name: proposal
          $ref: '#/components/parameters/proposalId'
      responses:
        '200':
          $ref: '#/components/responses/200'

  /badges/{address}:
    get:
      tags:
        - Badges
      summary: Get badges for the given address
      parameters:
        - name: address
          $ref: '#/components/parameters/address'
      responses:
        '200':
          $ref: '#/components/responses/200'
        '400':
          $ref: '#/components/responses/400'

  /user/{address}/is-validated:
    get:
      tags:
        - Users
      summary: Check if the given address is validated
      parameters:
        - name: address
          $ref: '#/components/parameters/address'
      responses:
        '200':
          $ref: '#/components/responses/200'

############# COMPONENTS #############

components:
  ## Schemas
  schemas:
    coauthorStatus:
      type: string
      pattern: '(APPROVED|REJECTED|PENDING)'
    ethAddress:
      type: string
      pattern: '^0x[a-fA-F0-9]{40}$'
    proposalType:
      type: string
      pattern: '(poi|catalyst|ban_name|grant|linked_wearables|poll|draft|governance|hiring)'
    proposalStatus:
      type: string
      pattern: '(pending|active|finished|rejected|passed|enacted|deleted)'
    order:
      type: string
      pattern: '(ASC|DESC)'
    limitOffset:
      type: integer
      minimum: 0
    url:
      type: string
      pattern: '^(https:\/\/)([a-zA-Z0-9._-]+)(:[0-9]+)?(\/[a-zA-Z0-9._-]*)*(\?[a-zA-Z0-9._-]*)?(\#[a-zA-Z0-9._-=]*)?$'
  ## Parameters
  parameters:
    user:
      name: user
      in: query
      description: User eth address
      schema:
        $ref: '#/components/schemas/ethAddress'
    proposalType:
      name: type
      in: query
      description: Proposal type
      example: poi
      schema:
        $ref: '#/components/schemas/proposalType'
    proposalStatus:
      name: status
      in: query
      description: Proposal status
      example: enacted
      schema:
        $ref: '#/components/schemas/proposalStatus'
    isSubscribed:
      name: subscribed
      in: query
      description: is user subscribed to the proposals
      schema:
        type: boolean
    isCoauthor:
      name: coauthor
      in: query
      description: is user coauthoring the proposals
      schema:
        type: boolean
    search:
      name: search
      in: query
      description: text included within the proposals
      schema:
        type: string
    timeFrame:
      name: timeFrame
      in: query
      example: 2days
      schema:
        type: string
    timeFrameKey:
      name: timeFrameKey
      in: query
      example: finish_at
      schema:
        type: string
    order:
      name: order
      in: query
      description: ascending or descending
      example: ASC
      schema:
        $ref: '#/components/schemas/order'
    limit:
      name: limit
      in: query
      schema:
        $ref: '#/components/schemas/limitOffset'
    offset:
      name: offset
      in: query
      schema:
        $ref: '#/components/schemas/limitOffset'
    snapshotIds:
      name: snapshotIds
      in: query
      description: snapshot proposal IDs
      schema:
        type: string
    image_url:
      name: url
      in: query
      description: image URL
      schema:
        $ref: '#/components/schemas/url'
    address:
      name: address
      in: path
      description: User eth address
      required: true
      schema:
        $ref: '#/components/schemas/ethAddress'
    proposalId:
      name: proposal
      in: path
      description: Proposal ID
      required: true
      schema:
        type: string
    updateId:
      name: update
      in: path
      description: Update ID
      required: true
      schema:
        type: string
    coauthorStatus:
      name: status
      in: path
      description: Request status
      required: true
      schema:
        $ref: '#/components/schemas/coauthorStatus'
  ## Responses
  responses:
    '200':
      description: successful operation
    '404':
      description: not found