openapi: 3.0.0
info:
  description: |
    News published to the Homepage channel.  
    Production server URL: https://api.schedulr.ch  
    Development server URL: https://api.dev.schedulr.ch
  version: 1.0.0
  title: Homepage Channel News API
  contact:
    email: tech@interactionpartners.ch
paths:
  /homepage-news:
    get:
      summary: List of news published to the homepage channel
      parameters:
        - $ref: '#/components/parameters/offsetParam'
        - $ref: '#/components/parameters/limitParam'
        - $ref: '#/components/parameters/sortParam'
        - $ref: '#/components/parameters/modifiedSinceParam'
      responses:
        '200':
          description: News list
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    type: integer
                    example: 230
                  limit:
                    type: integer
                    example: 20
                  offset:
                    type: integer
                    example: 0
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/News'
        '401':
          $ref: '#/components/responses/unauthorized'
  /homepage-news/{id}:
    parameters:
      - name: id
        in: path
        required: true
        description: News id
        schema:
          type: integer
    get:
      summary: Single news item published the homepage channel
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/News'
        '401':
          $ref: '#/components/responses/unauthorized'
        '404':
          $ref: '#/components/responses/notFound'
components:
  parameters:
    offsetParam:
      in: query
      name: offset
      description: Number of records to skip for pagination
      schema:
        type: integer
        minimum: 0
    limitParam:
      in: query
      name: limit
      description: Maximum number of records to return (max 20)
      schema:
        type: integer
        minimum: 0
        maximum: 20
    sortParam:
      in: query
      name: sort
      description: >-
        Sort by creation or publication dates. For example to sort by created_at
        ASC use "sort=created_at". For DESC it would be "sort=-created_at".
      schema:
        type: string
        enum:
          - created_at
          - '-created_at'
          - updated_at
          - '-updated_at'
          - published_at
          - '-published_at'
    modifiedSinceParam:
      in: query
      name: modified_since
      description: >-
        Returns created and updated news since specified time (in ISO8601
        format). Be careful - value must be URL-encoded (+ sign will convert
        into a space without encoding)
      schema:
        type: string
      example: '2022-02-01T21:11:25+00:00'
  responses:
    unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            type: object
            properties:
              errors:
                type: array
                items:
                  type: object
                  properties:
                    message:
                      type: string
                      example: Unauthorized
    notFound:
      description: Not found
      content:
        application/json:
          schema:
            type: object
            properties:
              errors:
                type: array
                items:
                  type: object
                  properties:
                    message:
                      type: string
                      example: Not found
  schemas:
    News:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        author:
          type: string
          nullable: true
          example: Jane Doe
        news_date:
          type: string
          format: date<yyyy-MM-dd>
          example: '2023-08-23'
        news_datetime:
          type: string
          format: date-time<ISO 8601>
          example: '2023-08-01T06:56:11+00:00'
        ad_hoc:
          type: boolean
        tags:
          type: array
          items:
            type: object
            properties:
              id:
                type: integer
                example: 23
              name:
                type: string
                example: Announcement
        translations:
          type: array
          items:
            $ref: '#/components/schemas/NewsTranslation'
        created_at:
          type: string
          format: date-time<ISO 8601>
          example: '2023-08-01T06:56:11+00:00'
        updated_at:
          type: string
          format: date-time<ISO 8601>
          example: '2023-08-01T06:56:11+00:00'
    NewsTranslation:
      type: object
      properties:
        language:
          type: string
          example: en
        title:
          type: string
          example: Example Title
        header:
          type: string
          nullable: true
          example: >-
            Ut nec porttitor sem. Ut sed risus feugiat, vehicula ipsum eu,
            consectetur nibh. Pellentesque habitant morbi tristique senectus et
            netus et malesuada fames ac turpis egestas.
        content:
          type: string
          example: >-
            In ut libero at nisl tristique viverra. Sed nibh mi, egestas sed
            volutpat blandit, interdum ac elit. Aenean blandit diam nunc, nec
            ornare urna aliquam ac. Phasellus sodales dui a scelerisque laoreet.
        footer:
          type: string
          nullable: true
          example: >-
            Nullam ultrices, erat et euismod varius, justo nibh finibus tellus,
            quis fringilla magna elit ac magna. Nulla vitae sem vestibulum,
            ultrices elit eu, ornare magna.
        thumbnail:
          type: string
          nullable: true
          format: uri
          example: https://example.com/example.jpg
        created_at:
          type: string
          format: date-time<ISO 8601>
          example: '2023-08-01T06:56:11+00:00'
        updated_at:
          type: string
          format: date-time<ISO 8601>
          example: '2023-08-01T06:56:11+00:00'
        attachments:
          type: array
          items:
            $ref: '#/components/schemas/Attachment'
        ad_hoc_text:
          type: string
          nullable: true
          example: Ad hoc announcement
    Attachment:
      type: object
      properties:
        name:
          type: string
          example: Example Document
        url:
          type: string
          format: uri
          example: https://example.com/example.pdf
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-Authorization
security:
  - apiKeyAuth: []
servers:
  - description: Dev server
    url: https://api.dev.schedulr.ch/
  - description: Production server
    url: https://api.schedulr.ch/
