openapi: 3.2.0
info:
  title: Eclipse Newsroom REST Featured Story API
  version: '1.0'
  description: REST API for interacting with newsroom different endpoints.
servers:
- url: https://newsroom.eclipse.org
  description: The production API server
tags:
- name: Featured Story
paths:
  /api/featured-story:
    get:
      tags:
      - Featured Story
      summary: List featured stories
      description: Retrieve featured stories.
      parameters:
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/PageSize'
      - $ref: '#/components/parameters/PublishToFilter'
      - name: parameters[type]
        in: query
        description: Filter featured story by type
        required: false
        schema:
          type: string
          enum:
          - story
          - footer
          - both
          - toolbar
          - popup
        example: story
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                required:
                - featured_story
                - pager
                properties:
                  featured_story:
                    type: array
                    items:
                      $ref: '#/components/schemas/FeaturedStory'
                  pager:
                    $ref: '#/components/schemas/Pager'
              example:
                featured_story:
                - id: '00001'
                  title: Example Featured Story Title
                  start-date: '2026-01-01T12:00:00'
                  end-date: '2026-01-31T22:00:00'
                  links:
                  - url: https://newsroom.eclipse.org/resources/example-report
                    title: Download the Example Report
                    original_url: https://newsroom.eclipse.org/resources/example-report
                    original_title: Download the Example Report
                  layout: light
                  type: story
                  body: ''
                  image: ''
                  publish_to:
                  - eclipse_org
                pager:
                  current_page: 0
                  total_items: '12'
                  total_pages: 1
                  items_per_page: '20'
      operationId: getApiFeaturedStory
      x-operation-id-source: derived
components:
  schemas:
    FeaturedStory:
      type: object
      required:
      - title
      - type
      - layout
      - start-date
      - end-date
      - publish_to
      properties:
        id:
          type: string
        title:
          type: string
        start-date:
          type: string
          format: date-time
        end-date:
          type: string
          format: date-time
        links:
          type: array
          items:
            $ref: '#/components/schemas/FeaturedStoryLink'
        layout:
          type: string
        type:
          type: string
        body:
          type: string
        image:
          type: string
          format: uri
        publish_to:
          type: array
          items:
            type: string
    FeaturedStoryLink:
      type: object
      properties:
        url:
          type: string
          format: uri
        title:
          type: string
        original_url:
          type: string
          format: uri
        original_title:
          type: string
    Pager:
      type: object
      required:
      - current_page
      - total_items
      - total_pages
      - items_per_page
      properties:
        current_page:
          type: integer
          format: int32
        total_items:
          type: string
        total_pages:
          type: integer
          format: int32
        items_per_page:
          type: string
  parameters:
    PublishToFilter:
      name: parameters[publish_to]
      in: query
      description: Filter events by publication target
      required: false
      schema:
        type: string
        enum:
        - eclipse_org
        - aice
        - adoptium
        - asciidoc
        - ecd_tools
        - dataspace
        - eclipse_events
        - edge_native
        - eclipse_ide
        - eclipse_iot
        - orc
        - research
        - security
        - sdv
        - sparkplug
        - jakarta_ee
        - oniro
        - openadx
        - opengenesis
        - openhwgroup
        - openmdm
        - openmobility
        - open_vsx
        - openpass
        - osgi
        - ospo_zone
        - science
        - tangle_ee
      example: eclipse_org
    PageSize:
      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
    Page:
      name: page
      in: query
      description: The number of the page.
      style: form
      explode: true
      schema:
        type: integer
        format: int32