# Feed endpoints powered by the MCS

tags:
  - name: Feed
    description: aggregated daily featured content
paths:
  /featured/{yyyy}/{mm}/{dd}:
    get:
      tags:
        - Feed
      summary: Aggregated featured content
      description: |
        Provides the aggregated feed content for the given date. The endpoint returns
        the featured article of the day, most read articles for the previous day, news
        content and the featured image and video of the day.

        Stability: [unstable](https://www.mediawiki.org/wiki/API_versioning#Unstable)
      produces:
        - application/json
      parameters:
        - name: yyyy
          in: path
          description: 'Year the aggregated content is requested for'
          type: string
          required: true
        - name: mm
          in: path
          description: 'Month the aggregated content is requested for, 0-padded'
          type: string
          required: true
        - name: dd
          in: path
          description: 'Day of the month the aggregated content is requested for, 0-padded'
          type: string
          required: true
      responses:
        '200':
          description: JSON containing all of the featured content
          schema:
            $ref: '#/definitions/feed'
        default:
          description: Error
          schema:
            $ref: '#/definitions/problem'
      operationId: aggregatedFeed
      x-monitor: true
      x-amples:
        - title: Retrieve aggregated feed content for April 29, 2016
          request:
            params:
              domain: en.wikipedia.org
              yyyy: '2016'
              mm: '04'
              dd: '29'
          response:
            status: 200
            headers:
              content-type: /application\/json/
            body:
              tfa:
                title: /.+/
                description: /.+/
                extract: /.+/
                thumbnail:
                  source: /.+/
                  width: /.+/
                  height: /.+/
              mostread:
                date: /.+/
                articles:
                  - views: /.+/
                    rank: /.+/
                    title: /.+/
                    pageid: /.+/
                    normalizedtitle: /.+/
              image:
                title: /.+/
                description:
                  text: /.+/
                  lang: /.+/
                image:
                  source: /.+/
                  width: /.+/
                  height: /.+/
                thumbnail:
                  source: /.+/
                  width: /.+/
                  height: /.+/

definitions:
  mostread_article:
    type: object
    properties:
      title:
        type: string
        description: Article title in a form of DB key
      normalizedtitle:
        type: string
        description: Article title as it should be presented to the user
      views:
        type: integer
        description: Number of views on the requested day
      rank:
        type: integer
        description: Position in the list of most viewed articles
      thumbnail:
        description: Lead image for the article
        $ref: '#/definitions/thumbnail'
      description:
        type: string
        description: Wikidata description of the article
      extract:
        type: string
        description: First several sentences of an article in plain text
    required:
      - title
      - normalizedtitle
      - views
      - rank
      - pageid

  mostread:
    type: object
    properties:
      date:
        type: string
        description: The date which the data correspond to
      articles:
        type: array
        description: Array of most popular articles
        items:
          $ref: '#/definitions/mostread_article'
    required:
      - date
      - articles

  news_item:
    type: object
    properties:
      story:
        type: string
        description: A cover story for the news item
      links:
        type: array
        description: A collection of articles related to the news item
        items:
          $ref: '#/definitions/summary'
    required:
      - story
      - links

  news:
    type: array
    items:
      $ref: '#/definitions/news_item'

  image_description:
    properties:
      text:
        type: string
        description: Text of the description
      lang:
        type: string
        description: Language code of the description
    required:
      - text
      - lang

  image:
    type: object
    properties:
      title:
        type: string
        description: Image title
      thumbnail:
        description: Image thumbnail
        $ref: '#/definitions/thumbnail'
      image:
        description: Full-size image
        $ref: '#/definitions/thumbnail'
      description:
        descrtiption: Description of an image
        $ref: '#/definitions/image_description'
    required:
      - title
      - thumbnail
      - image

  onthisday:
    type: array
    items:
      type: object
      properties:
        text:
          type: string
          description: Short description of the event
        pages:
          type: array
          description: List of pages related to the event
          items:
            $ref: '#/definitions/summary'

  feed:
    type: object
    description: Aggregated feed content for a given date
    properties:
      tfa:
        description: Data about the featured article of the day
        $ref: '#/definitions/summary'
      mostread:
        description: Data about most viewed articles
        $ref: '#/definitions/mostread'
      news:
        description: Data about in the news section
        $ref: '#/definitions/news'
      image:
        description: Featured image for a given date
        $ref: '#/definitions/image'
      onthisday:
        description: List of featured events that happend on this day
        $ref: '#/definitions/onthisday'
    additionalProperties: false