openapi: 3.2.0
info:
  version: 1.0.0
  title: Membership portal Organizations API
  description: API used for reading and updating information about member organizations and it's associated metadata.
  contact:
    name: Software Development Team
    url: https://gitlab.eclipse.org/eclipsefdn/software-dev
    email: software-dev@eclipse-foundation.org
  license:
    name: Eclipse Public License - 2.0
    url: https://www.eclipse.org/legal/epl-2.0/
servers:
- url: https://membership.eclipse.org/api
  description: Production endpoint for the membership portal data
tags:
- name: Organizations
  description: Definitions related to Eclipse Foundation organizations
paths:
  /organizations:
    get:
      tags:
      - Organizations
      summary: Organizations List
      description: Returns a list of organizations from the Eclipse API
      operationId: listOrganizations
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Organizations'
        '500':
          description: Error while retrieving data
  /organizations/slim:
    get:
      tags:
      - Organizations
      summary: Slim Organizations List
      description: Returns a list of paired down organizations from the Eclipse API, returning just critical data
      operationId: listOrganizationsSlim
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SlimOrganizations'
        '500':
          description: Error while retrieving data
  /organizations/{organizationID}:
    parameters:
    - name: organizationID
      in: path
      description: The organization ID for the organization to retrieve
      required: true
      schema:
        type: number
    get:
      tags:
      - Organizations
      summary: Organization
      description: Returns an organization that has a matching ID
      operationId: getOrganization
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Organization'
        '500':
          description: Error while retrieving data
    post:
      tags:
      - Organizations
      summary: Organization Info update
      description: Updates an organization information and returns the updated entity
      operationId: updateOrganization
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrganizationInfoUpdateRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Organization'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '500':
          description: Error while retrieving data
        '503':
          description: Error while retrieving data
  /organizations/{organizationID}/cbi:
    parameters:
    - name: organizationID
      in: path
      description: The organization ID for the organization to retrieve
      required: true
      schema:
        type: number
    get:
      tags:
      - Organizations
      summary: Organization CBI
      description: Returns the CBI information for the current organization
      operationId: getOrganizationCBI
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationCBI'
        '404':
          description: No CBI information found for given organization
  /organizations/{organizationID}/logos:
    parameters:
    - name: organizationID
      in: path
      description: The organization ID for the organization to retrieve
      required: true
      schema:
        type: number
    post:
      security:
      - openId: []
      tags:
      - Organizations
      summary: Organization logo update
      description: Updates an organization logo and returns the updated entity
      operationId: updateOrganizationLogos
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/OrganizationLogoUpdateRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Organization'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '500':
          description: Error while retrieving data
    delete:
      parameters:
      - name: type
        in: query
        description: The type of logo format to remove, e.g. WEB or PRINT. Defaults to WEB when not provided
        schema:
          type: string
      security:
      - openId: []
      tags:
      - Organizations
      summary: Organization logo delete
      description: Removes an organization logo if one exists
      operationId: deleteOrganizationLogo
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/OrganizationLogoUpdateRequest'
      responses:
        '204':
          description: Success
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '500':
          description: Error while retrieving data
  /organizations/{organizationID}/projects:
    parameters:
    - name: organizationID
      in: path
      description: The organization ID for the associated entities to retrieve
      required: true
      schema:
        $ref: '#/components/schemas/ObjectID'
    get:
      tags:
      - Organizations
      summary: Organization Projects
      description: Returns projects associated with the organization
      operationId: getOrganizationProjects
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Projects'
        '500':
          description: Error while retrieving data
  /organizations/{organizationID}/committers:
    parameters:
    - name: organizationID
      in: path
      description: The organization ID for the associated entities to retrieve
      required: true
      schema:
        $ref: '#/components/schemas/ObjectID'
    get:
      security:
      - openId: []
      tags:
      - Organizations
      summary: Organization Committers
      description: Returns committers associated with the organization
      operationId: getOrganizationCommitters
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnhancedPersons'
        '500':
          description: Error while retrieving data
  /organizations/{organizationID}/contributors:
    parameters:
    - name: organizationID
      in: path
      description: The organization ID for the associated entities to retrieve
      required: true
      schema:
        $ref: '#/components/schemas/ObjectID'
    get:
      security:
      - openId: []
      tags:
      - Organizations
      summary: Organization Contributors
      description: Returns contributors associated with the organization
      operationId: getOrganizationContributors
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnhancedPersons'
        '500':
          description: Error while retrieving data
  /organizations/{organizationID}/web-logo:
    parameters:
    - name: organizationID
      in: path
      description: The organization ID for the organization to retrieve
      required: true
      schema:
        type: number
    get:
      tags:
      - Organizations
      summary: Organization web-logo
      description: Generic URL for fetching the web logo of an organization via redirect
      operationId: getOrganizationWebLogo
      responses:
        '302':
          description: Success, redirect to web logo
        '404':
          description: No logo found
        '500':
          description: Error while retrieving data
  /organizations/{organizationID}/working_groups:
    parameters:
    - name: organizationID
      in: path
      description: The organization ID for the organization to retrieve
      required: true
      schema:
        type: number
    get:
      tags:
      - Organizations
      summary: Organization working groups
      description: Gets working groups the organization is member to
      operationId: getOrganizationWorkingGroups
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkingGroups'
        '404':
          description: No organization found
        '500':
          description: Error while retrieving data
components:
  schemas:
    SlimOrganization:
      type: object
      additionalProperties: false
      required:
      - organization_id
      - name
      - logos
      - is_active_member
      - website
      properties:
        organization_id:
          type: integer
          description: The unique ID for the given organization
        name:
          type: string
          description: The display name of the organization
        website:
          type:
          - string
          - 'null'
          description: The website for the given organization, used for linking back to the member
        is_active_member:
          type: boolean
          description: Whether the organization is an active or historic member.
        logos:
          type: object
          properties:
            print:
              type:
              - string
              - 'null'
              description: URL of full resolution logo
            web:
              type:
              - string
              - 'null'
              description: URL of compressed web logo
    DateTime:
      type: string
      format: datetime
      description: 'Date string in the RFC 3339 format. Example, `1990-12-31T"15":"59":60-"08":00`.


        More on this standard can be read at https://tools.ietf.org/html/rfc3339.

        '
    ObjectID:
      description: Unique identifier for an addressable object in the API. Can be null when posting or updating objects in the API if part of the root element or is a new entity. Should always be set in responses.
      type:
      - string
      - 'null'
      minimum: 1
    EnhancedPersons:
      type: array
      items:
        $ref: '#/components/schemas/EnhancedPersonData'
    Organizations:
      type: array
      items:
        $ref: '#/components/schemas/Organization'
    Projects:
      type: array
      items:
        $ref: '#/components/schemas/Project'
    WorkingGroups:
      type: array
      items:
        $ref: '#/components/schemas/WorkingGroup'
    OrganizationLogoUpdateRequest:
      type: object
      properties:
        image:
          type: object
          description: The image file. Should be included as a file would naturally be included in a form without encoding
        image_mime:
          type: string
          description: The mime type for the image
        image_format:
          type: string
          description: the format of logo image to be updated
          enum:
          - SMALL
          - LARGE
          - PRINT
    SlimOrganizations:
      type: array
      items:
        $ref: '#/components/schemas/SlimOrganization'
    Project:
      type: object
      properties:
        project_id:
          $ref: '#/components/schemas/ObjectID'
        parent_project_id:
          $ref: '#/components/schemas/ObjectID'
        name:
          type: string
          description: Placeholder
        level:
          type: string
          description: Placeholder
        description:
          type: string
          description: Placeholder
        url_download:
          type: string
          description: Placeholder
        url_index:
          type: string
          description: Placeholder
        date_active:
          $ref: '#/components/schemas/DateTime'
        sort_order:
          type: string
          description: Placeholder
        bugs_name:
          type: string
          description: Placeholder
        project_phase:
          type: string
          description: Placeholder
        disk_quota_gb:
          type: integer
          description: Placeholder
        is_active:
          type: boolean
          description: Placeholder
        is_component:
          type: boolean
          description: Placeholder
        is_standard:
          type: boolean
          description: Placeholder
    WorkingGroupParticipationAgreement:
      type: object
      properties:
        document_id:
          $ref: '#/components/schemas/ObjectID'
        pdf:
          type: string
          description: Link to the PDF version of the participation agreement
    Organization:
      type: object
      additionalProperties: false
      required:
      - organization_id
      - name
      - description
      - website
      - logos
      - levels
      - wgpas
      - member_since
      - renewal_date
      - is_active_member
      properties:
        organization_id:
          type: integer
        name:
          type: string
        renewal_date:
          type: string
        member_since:
          type: string
        is_active_member:
          type: boolean
          description: True if the organization is an active member
        levels:
          type: array
          items:
            type: object
            properties:
              level:
                type: string
              description:
                type: string
        description:
          type:
          - object
          - 'null'
          properties:
            short:
              type: string
            full:
              type: string
        website:
          type:
          - string
          - 'null'
        logos:
          type:
          - object
          - 'null'
          properties:
            print:
              type:
              - string
              - 'null'
              description: URL of full resolution logo
            web:
              type:
              - string
              - 'null'
              description: URL of compressed web logo
        wgpas:
          type: array
          items:
            type: object
            properties:
              document_id:
                $ref: '#/components/schemas/ObjectID'
              level:
                type: string
              working_group:
                type: string
              description:
                type: string
    OrganizationInfoUpdateRequest:
      type: object
      properties:
        description:
          type: string
          description: Description of the stored URL/product
        company_url:
          type: string
          description: URL for the product
    EnhancedPersonData:
      type: object
      required:
      - id
      - first_name
      - last_name
      - relations
      properties:
        id:
          type: string
          description: Description of the stored URL/product
        first_name:
          type: string
          description: First name of the user
        last_name:
          type: string
          description: Last name of the user
        email:
          oneOf:
          - type: string
          - type: 'null'
          description: Email of the user. Only included if the current user has elevated permissions for the current organization.
        relations:
          type: array
          description: list of relation codes that are active for the current user
          items:
            type: string
    WorkingGroup:
      type: object
      properties:
        alias:
          type: string
          description: internal alias for the working group
        title:
          type: string
          description: Public-facing or official name of the working group
        status:
          type: string
          description: Current status of the working group (e.g. incubating, active, archived)
        logo:
          type: string
          description: image link for the working groups logo
        description:
          type: string
          description: Short description of the working group
        resources:
          type: object
          properties:
            charter:
              type: string
              description: Link to the charter for the current working group
            contact_form:
              type: string
              description: URL link to the contact form
            members:
              type: string
              description: URL to the members list for the given working group
            participation_agreements:
              type: object
              properties:
                individual:
                  anyOf:
                  - type: 'null'
                  - $ref: '#/components/schemas/WorkingGroupParticipationAgreement'
                organization:
                  anyOf:
                  - type: 'null'
                  - $ref: '#/components/schemas/WorkingGroupParticipationAgreement'
                sponsorship:
                  type: string
                  description: link to the sponsorship agreement document
                sponsorship_document:
                  type:
                  - string
                  - 'null'
                  description: Sponsorship agreement document in Foundation for formalized sponsorship
            website:
              type: string
              description: the URL for the homepage of this working group
        levels:
          type: array
          items:
            type: object
            description: Definition of the participation level for the working group, including its relation code
            properties:
              relation:
                type: string
                description: code representing the relation, used internally when using common relation types
              description:
                type: string
                description: the label for the participation level
    OrganizationCBI:
      type: object
      properties:
        memberOrganizationsBenefits:
          type: array
          items:
            type: object
            properties:
              id:
                type: number
                description: The numeric ID of the organization that granted the following resources
              displayName:
                type: string
                description: the display name of the Organization that granted the following resources to the project from its allotment
              resourcePacks:
                type: number
                description: the number of resource packs granted to the member as part of their membership
              dedicatedAgents:
                type: number
                description: the number of dedicated agents granted to the member as part of their membership
              ghLargeRunners:
                type: number
                description: the number of large Github job runners granted to the member as part of their membership
              resourcePacks_used:
                type: number
                description: the number of resource packs allocated by the member to projects
              dedicatedAgents_used:
                type: number
                description: the number of dedicated agents allocated by the member to projects
              ghLargeRunners_used:
                type: number
                description: the number of large Github job runners allocated by the member to projects
              membership:
                type: string
                description: The organization in which the organization has a membership with (e.g. Eclipse or OpenHardware)
        sponsoredProjects:
          type: array
          items:
            type: object
            properties:
              project:
                type: object
                properties:
                  id:
                    type: string
                    description: Name of the project that has sponsored CBI packs
              sponsoringOrganizations:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: number
                      description: The numeric ID of the organization that granted the following resources
                    displayName:
                      type: string
                      description: the display name of the Organization that granted the following resources to the project from its allotment
                    resourcePacks:
                      type: number
                      description: the number of resource packs granted to the project
                    dedicatedAgents:
                      type: number
                      description: the number of dedicated agents granted to the project
                    ghLargeRunners:
                      type: number
                      description: the number of large Github job runners granted to the project
                    comment:
                      type: string
                      description: Comments associated with the granted resources
                    requestTickets:
                      type: array
                      items:
                        type: string
                        description: Ticket linking to the request from the organization to add the resources/agents to this project.
  securitySchemes:
    openId:
      type: openIdConnect
      openIdConnectUrl: https://auth.eclipse.org/auth/realms/foundation/.well-known/openid-configuration