Eclipse Foundation Proposals API

openapi: 3.2.0
info:
  title: Eclipse Project Management Infrastructure (PMI) RESTful…
  description: 'This describes the resources that make up the Eclipse Project Management Infrastructure (PMI) REST API.

    You can contribute to this document via our git repository.

    If you have any problems or requests please submit an issue.


    ### Rate Limit

    This API currently limits users to 1000 authenticated requests and 1000 anonymous requests an hour.

    ### Pagination

    Information about pagination is provided in the Link header of an API call. For example, let''s make a curl request to the eclipse_profile API, to find out how many org_eclipse_oomph records exist for the user:

    ```

    curl -I \"https://projects.eclipse.org/api/projects?page=1&pagesize=20\"

    ```

    The -I parameter indicates that we only care about the headers, not the content. In examining the result, you''ll notice some information in the Link header that looks like this:

    ```

    ; rel="next",

    ; rel="last",

    ; rel="first",

    ; rel="self"

    ```

    Let''s break that down. rel=\"next\" says that the next page is page=2. This makes sense, since by default, all paginated queries start at page 1. rel=\"last\" provides some more information, stating that the last page of results is on page 27.

    Keep in mind that you should always rely on these link relations provided to you. Don''t try to guess or construct your own URL.


    ### Error States

    The common HTTP Response Status Codes are used.'
  contact: {}
  version: '1.0'
servers:
- url: https://projects.eclipse.org
  description: The production API server
tags:
- name: Proposals
  description: Eclipse project proposals submitted for community review.
paths:
  /api/proposals:
    get:
      tags:
      - Proposals
      summary: Fetch Proposals
      description: '### Overview


        Retrieve a paginated list of Eclipse project proposals.


        Unlike the projects index, pagination metadata is included in the response body alongside the `result` array, in addition to the `Link` header.'
      operationId: FetchProposals
      parameters:
      - name: spec_project
        in: query
        description: Filter to specification projects only. Set to any non-zero integer to enable.
        style: form
        explode: true
        schema:
          type: integer
          format: int32
          default: 0
      - name: spec_project_working_group
        in: query
        description: Filter by specification project working group ID.
        style: form
        explode: true
        schema:
          type: string
      - name: industry_collaboration
        in: query
        description: Filter by industry collaboration (working group) ID.
        style: form
        explode: true
        schema:
          type: string
      - name: state
        in: query
        description: Filter by proposal state (case-insensitive). Accepts a single value (`state=Active`) or an array (`state[]=Active&state[]=Draft`).
        style: form
        explode: true
        schema:
          type: string
      - name: page
        in: query
        description: The index of the page to retrieve, defaults to 1.
        style: form
        explode: true
        schema:
          type: integer
          format: int32
          default: 1
          minimum: 1
      - name: pagesize
        in: query
        description: The number of records to get per page, defaults to 20. Maximum value is 100.
        style: form
        explode: true
        schema:
          type: integer
          format: int32
          default: 20
          minimum: 1
          maximum: 100
      - name: order_by
        in: query
        description: 'The order in which results are returned. Defaults to `ASC`. Accepted values: `ASC`, `DESC`, `RANDOM`.'
        style: form
        explode: true
        schema:
          type: string
          default: ASC
      responses:
        '200':
          description: A paginated wrapper object containing the proposals and pagination metadata.
          headers:
            Link:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProposalsIndexResponse'
              example:
                result:
                - id: 789
                  project_id: technology.new-project
                  name: New Eclipse Project Proposal
                  parent: technology
                  top_level_project: technology
                  industry_collaborations: []
                  state: Active
                  summary: A short plain-text summary of the proposal.
                  scope: ''
                  background: ''
                  date: '2023-06-01'
                  url: https://projects.eclipse.org/proposals/new-project
                  project_url: ''
                  spec_project: []
                  committers: []
                  project_leads: []
                  patent_license: ''
                  licenses:
                  - Eclipse Public License 2.0
                  repo_type: Git
                  repos:
                  - https://github.com/eclipse/new-project
                pagination:
                  page: 1
                  pagesize: 20
                  result_start: 1
                  result_end: 1
                  result_size: 1
                  total_result_size: 1
  /api/proposals/{nid}:
    get:
      tags:
      - Proposals
      summary: Retrieve a Proposal
      description: '### Overview


        Retrieve a single Eclipse project proposal by its Drupal node ID.'
      operationId: RetrieveAProposal
      parameters:
      - name: nid
        in: path
        description: The Drupal node ID of the proposal.
        required: true
        style: simple
        explode: false
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: An array containing the matching proposal.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Proposal'
              example:
              - id: 789
                project_id: technology.new-project
                name: New Eclipse Project Proposal
                parent: technology
                top_level_project: technology
                industry_collaborations: []
                state: Active
                summary: A short plain-text summary of the proposal.
                scope: ''
                background: ''
                date: '2023-06-01'
                url: https://projects.eclipse.org/proposals/new-project
                project_url: ''
                spec_project: []
                committers: []
                project_leads: []
                patent_license: ''
                licenses:
                - Eclipse Public License 2.0
                repo_type: Git
                repos:
                - https://github.com/eclipse/new-project
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    SpecProjectWorkingGroup:
      title: SpecProjectWorkingGroup
      required:
      - name
      - id
      type: object
      properties:
        name:
          type: string
        id:
          type: string
      example:
        name: Jakarta EE
        id: jakarta-ee
    Committer:
      title: Committer
      type: object
      description: A person with a role on an Eclipse project (committer, contributor, or project lead).
      required:
      - username
      - url
      properties:
        username:
          type:
          - string
          - 'null'
          description: Eclipse account username (may be null for proposals where the person has no account yet).
        full_name:
          type: string
          description: Display name of the person.
        url:
          type: string
          description: Absolute URL to the person's profile on api.eclipse.org.
      example:
        username: acommitter
        full_name: A Committer
        url: https://api.eclipse.org/account/profile/acommitter
    Proposal:
      title: Proposal
      type: object
      properties:
        id:
          type: integer
          description: Drupal node ID of the proposal.
        project_id:
          type: string
          description: Proposed Eclipse project identifier.
        name:
          type: string
          description: Proposal title.
        parent:
          type: string
          description: Project ID of the parent project, or empty string.
        top_level_project:
          type: string
          description: Project ID of the top-level project, or empty string.
        industry_collaborations:
          type: array
          items:
            $ref: '#/components/schemas/WorkingGroup'
          description: Working groups / industry collaborations associated with this proposal.
        state:
          type: string
          description: Current proposal state (e.g. `Active`, `Draft`, `Withdrawn`).
        summary:
          type: string
          description: Plain-text summary truncated to 200 characters (HTML stripped).
        scope:
          type: string
          description: Raw scope field text.
        background:
          type: string
          description: Raw background field text.
        date:
          type: string
          description: Proposal creation date in `Y-m-d` format.
        url:
          type: string
          description: Absolute URL to the proposal page.
        project_url:
          type: string
          description: Absolute URL to the resulting project page if the project already exists, otherwise empty string.
        spec_project:
          type: array
          items:
            $ref: '#/components/schemas/SpecProjectWorkingGroup'
          description: Specification working group(s) associated with this proposal (at most one entry).
        committers:
          type: array
          items:
            $ref: '#/components/schemas/Committer'
          description: Initial committers listed in the proposal. The `username` field may be null when a committer does not yet have an Eclipse account.
        project_leads:
          type: array
          items:
            $ref: '#/components/schemas/Committer'
          description: Proposed project leads.
        patent_license:
          type: string
          description: Patent license selected for this proposal.
        licenses:
          type: array
          items:
            type: string
          description: License term labels selected for this proposal.
        repo_type:
          type: string
          description: Source repository type (e.g. `Git`).
        repos:
          type: array
          items:
            type: string
          description: Source repository URIs.
      example:
        id: 789
        project_id: technology.new-project
        name: New Eclipse Project Proposal
        parent: technology
        top_level_project: technology
        industry_collaborations: []
        state: Active
        summary: A short plain-text summary of the proposal.
        scope: ''
        background: ''
        date: '2023-06-01'
        url: https://projects.eclipse.org/proposals/new-project
        project_url: ''
        spec_project: []
        committers: []
        project_leads: []
        patent_license: ''
        licenses:
        - Eclipse Public License 2.0
        repo_type: Git
        repos:
        - https://github.com/eclipse/new-project
    Pagination:
      title: Pagination
      type: object
      description: Pagination metadata included in some list responses.
      properties:
        page:
          type: integer
          description: Current page number (1-based).
        pagesize:
          type: integer
          description: Maximum number of results per page.
        result_start:
          type: integer
          description: One-based index of the first result on this page.
        result_end:
          type: integer
          description: One-based index of the last result on this page. -1 when the page is empty.
        result_size:
          type: integer
          description: Number of results on this page.
        total_result_size:
          type: integer
          description: Total number of results across all pages.
      example:
        page: 1
        pagesize: 20
        result_start: 1
        result_end: 20
        result_size: 20
        total_result_size: 150
    ProposalsIndexResponse:
      title: ProposalsIndexResponse
      type: object
      description: Paginated proposals list. Unlike the projects index, this endpoint preserves the pagination metadata in the response body alongside the `result` array.
      properties:
        result:
          type: array
          items:
            $ref: '#/components/schemas/Proposal'
        pagination:
          $ref: '#/components/schemas/Pagination'
      example:
        result:
        - id: 789
          project_id: technology.new-project
          name: New Eclipse Project Proposal
        pagination:
          page: 1
          pagesize: 20
          result_start: 1
          result_end: 1
          result_size: 1
          total_result_size: 1
    WorkingGroup:
      title: WorkingGroup
      required:
      - name
      - id
      type: object
      properties:
        name:
          type: string
        id:
          type: string
      example:
        name: Jakarta EE
        id: jakarta-ee
  responses:
    NotFound:
      description: Resource not found.
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string