openapi: 3.0.0
info:
  description: News CRUD API
  version: 1.0.0
  title: News API
  contact:
    email: tech@interactionpartners.ch
paths:
  /news:
    get:
      summary: News items of a company (without content)
      operationId: news-list
      parameters:
        - $ref: '#/components/parameters/offsetParam'
        - $ref: '#/components/parameters/limitParam'
        - $ref: '#/components/parameters/sortParam'
      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
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/NewsItemShort'
        '401':
          $ref: '#/components/responses/unauthorized'
    post:
      summary: Create a news item
      requestBody:
        $ref: '#/components/requestBodies/inputNewsItem'
      responses:
        '201':
          description: Successful creation response
        '401':
          $ref: '#/components/responses/unauthorized'
        '422':
          $ref: '#/components/responses/validationErrors'
  /news/{id}:
    parameters:
      - name: id
        in: path
        required: true
        description: News id
        schema:
          type: integer
    get:
      summary: News item details (with content)
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NewsItemFull'
        '401':
          $ref: '#/components/responses/unauthorized'
        '404':
          $ref: '#/components/responses/notFound'
    put:
      summary: Update news (substitutes all values, meaning works not like PATCH)
      requestBody:
        $ref: '#/components/requestBodies/inputNewsItem'
      responses:
        '201':
          description: Successful updating response
        '401':
          $ref: '#/components/responses/unauthorized'
        '404':
          $ref: '#/components/responses/notFound'
        '422':
          $ref: '#/components/responses/validationErrors'
    delete:
      summary: Delete the news
      responses:
        '200':
          description: News item deleted
        '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
  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: Unauthorized
      content:
        application/json:
          schema:
            type: object
            properties:
              errors:
                type: array
                items:
                  type: object
                  properties:
                    message:
                      type: string
                      example: Not found
    validationErrors:
      description: Validation errors
      content:
        application/json:
          schema:
            type: object
            properties:
              errors:
                type: object
  requestBodies:
    inputNewsItem:
      description: Callback payload
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NewsItemInput'
  schemas:
    NewsItemShort:
      allOf:
        - $ref: '#/components/schemas/_NewsId'
        - $ref: '#/components/schemas/_NewsMainProps'
        - $ref: '#/components/schemas/_CreatedUpdatedDates'
    NewsItemFull:
      allOf:
        - $ref: '#/components/schemas/_NewsId'
        - $ref: '#/components/schemas/_NewsMainProps'
        - type: object
          properties:
            content:
              type: array
              items:
                $ref: '#/components/schemas/_NewsContentTranslationFull'
        - $ref: '#/components/schemas/_NewsPublication'
        - $ref: '#/components/schemas/_CreatedUpdatedDates'
    NewsItemInput:
      required:
        - author_email
        - company_isin
        - content
        - published_at
        - ad_hoc
      allOf:
        - $ref: '#/components/schemas/_NewsMainProps'
        - type: object
          properties:
            content:
              type: array
              items:
                $ref: '#/components/schemas/_NewsContentTranslation'
        - $ref: '#/components/schemas/_NewsPublication'
    _NewsId:
      type: object
      properties:
        id:
          type: integer
          example: 789
    _NewsMainProps:
      type: object
      properties:
        name:
          type: string
          example: Internal news item name (actual titles are in translations)
        author_email:
          type: string
          format: email
          example: some-author@example.com
        company_isin:
          type: string
          example: US123456789
        news_date:
          type: string
          description: Display date
          example: '2022-02-22'
        news_datetime:
          type: string
          description: Display datetime
          format: date-time<ISO 8601>
          example: '2023-08-01T06:56:11+00:00'
        published_at:
          type: string
          description: >-
            Publishing date (if future then the item is scheduled for
            publishing)
          example: '2022-02-22T22:22:22+01:00'
        ad_hoc:
          type: boolean
          default: false
    _NewsContentTranslation:
      type: object
      required:
        - language
        - title
        - content
      properties:
        language:
          type: string
          example: en
        title:
          type: string
          example: Breaking news about something
        content:
          type: string
          example: >-
            Lorem ipsum <img src="https://werwerwer"/> dolor sit amet,
            consectetur adipiscing elit, sed do eiusmod...
    _NewsContentTranslationFull:
      allOf:
        - $ref: '#/components/schemas/_NewsContentTranslation'
        - $ref: '#/components/schemas/_CreatedUpdatedDates'
    _CreatedUpdatedDates:
      type: object
      properties:
        created_at:
          type: string
          description: When news item was created in schedulR
          example: '2022-01-18T06:58:30Z'
        updated_at:
          type: string
          description: Latest update of news item in schedulR
          example: '2022-01-18T06:58:30Z'
    _NewsPublication:
      type: object
      properties:
        publication:
          type: object
          properties:
            six:
              type: boolean
              example: true
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-Authorization
security:
  - apiKeyAuth: []
servers:
  - description: Dev server
    url: https://api.dev.schedulr.ch/
  - description: Production
    url: https://api.schedulr.ch/
