openapi: 3.2.0
info:
  version: 1.0.0
  title: Openvsx Publisher Agreement API
  description: Access information on Eclipse Foundation publisher agreements.
  license:
    name: Eclipse Public License - 2.0
    url: https://www.eclipse.org/legal/epl-2.0/
servers:
- url: https://api.eclipse.org/openvsx
  description: Production endpoint for Eclipse Foundation publisher agreement data
tags:
- name: Publisher Agreement
paths:
  /publisher_agreement:
    get:
      tags:
      - Publisher Agreement
      summary: Publisher Agreement
      description: Fetch the open-vsx.org publisher agreement for the current user.
      security:
      - OAuth2:
        - openvsx_publisher_agreement
        - openid
        - profile
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublisherAgreement'
        '404':
          description: Agreement not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Error while retrieving data
      operationId: getPublisherAgreement
      x-operation-id-source: derived
    post:
      tags:
      - Publisher Agreement
      summary: Create a Publisher Agreement
      description: Create an open-vsx.org publisher agreement for the current user.
      security:
      - OAuth2:
        - openvsx_publisher_agreement
        - openid
        - profile
      requestBody:
        description: Required information to sign an open-vsx.org publisher agreement.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgreementSigningRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublisherAgreement'
        '400':
          description: Invalid data
        '409':
          description: Conflict
        '500':
          description: Error while processing data
      operationId: postPublisherAgreement
      x-operation-id-source: derived
  /publisher_agreement/{ef_username}:
    parameters:
    - in: path
      name: ef_username
      required: true
      description: The Eclipse username.
      schema:
        type: string
    get:
      tags:
      - Publisher Agreement
      summary: Publisher Agreement for specific user
      description: Retrieve the open-vsx.org publisher agreement of a user. The current user can retrieve his own Publisher Agreement but only an admin can retrieve a Publisher Agreement of another user.
      security:
      - OAuth2:
        - openvsx_publisher_agreement
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublisherAgreement'
        '404':
          description: No agreement found for given user.
        '500':
          description: Error while retrieving data
      operationId: getPublisherAgreementByEfUsername
      x-operation-id-source: derived
    delete:
      tags:
      - Publisher Agreement
      summary: Delete Publisher Agreement for specific user
      description: Delete the open-vsx.org publisher agreement of a user.
      security:
      - OAuth2:
        - openvsx_publisher_agreement
      responses:
        '204':
          description: Accepted
        '404':
          description: No agreement found for given user.
        '500':
          description: Error while retrieving data
      operationId: deletePublisherAgreementByEfUsername
      x-operation-id-source: derived
components:
  schemas:
    PublisherAgreement:
      type: object
      additionalProperties: false
      required:
      - PersonID
      - DocumentID
      - Version
      - EffectiveDate
      - ReceivedDate
      - ScannedDocumentBLOB
      - ScannedDocumentMime
      - ScannedDocumentFileName
      - Comments
      properties:
        PersonID:
          type: string
          description: The id of the user tied to the publisher agreement.
        DocumentID:
          type: string
          description: The document id.
        Version:
          type: string
          description: The agreement version.
        EffectiveDate:
          type: string
          description: The effective date of the agreement.
        ReceivedDate:
          type: string
          description: The date the agreement was received.
        ScannedDocumentBLOB:
          type: string
          description: The scanned document byte blob.
        ScannedDocumentMime:
          type: string
          description: The scanned document mime type.
        ScannedDocumentFileName:
          type: string
          description: The scanned document file name.
        ScannedDocumentBytes:
          type: string
          description: The number of bytes in the BLOB for the document
        Comments:
          type: string
          description: Comments on the agreement.
    Error:
      type: object
      additionalProperties: false
      required:
      - status_code
      - message
      properties:
        status_code:
          type: integer
          description: HTTP response code
        message:
          type: string
          description: Message containing error information
        url:
          oneOf:
          - type: string
          - type: 'null'
          description: The URL
        friendly_message:
          oneOf:
          - type: string
          - type: 'null'
          description: The optional client-friendly error message
    AgreementSigningRequest:
      type: object
      additionalProperties: false
      required:
      - version
      - github_handle
      properties:
        version:
          type: string
          description: The version number of the document/agreement.
        github_handle:
          type: string
          description: The GitHub username of the user. This must match what the Eclipse Foundation has on file for the user to successfully sign the puglisher agreement.
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://accounts.eclipse.org/oauth2/authorize
          tokenUrl: https://accounts.eclipse.org/oauth2/token
          scopes:
            openvsx_publisher_agreement: Submit and revoke your open-vsx.org publisher agreement.
            openid: Know who you are on accounts.eclipse.org.
            email: View your email address.
            profile: View basic information about your account.