swagger: '2.0'
info:
  description: 'Dit is de publieke alleen-lezen interface van 6FM RES (Radio Extranet Systeem).'
  version: '1.0.0'
  title: '6FM RES'
  # termsOfService: 'http://swagger.io/terms/'
  contact:
    email: 'mischa.spelt@6fm.nl'
  #license:
  #  name: 'Apache 2.0'
  #  url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
basePath: '/'
tags:
- name: 'nieuws'
  description: 'Nieuwsberichten'
- name: 'agenda'
  description: 'Regioagenda-items'
- name: 'podcast'
  description: 'Podcasts'
  #externalDocs:
  #  description: 'Find out more'
  #  url: 'http://swagger.io'
#- name: 'store'
  #description: 'Access to Petstore orders'
#- name: 'user'
  #description: 'Operations about user'
  #externalDocs:
  #  description: 'Find out more about our store'
  #  url: 'http://swagger.io'
schemes:
- 'http'
paths:
  '/nieuws/overzicht':
    get:
      tags:
      - 'nieuws'
      summary: 'Overzicht van nieuwsberichten'
      description: 'Geeft een overzicht van {aantal} recente nieuwsberichten, de meest recente {pagina} pagina''s overslaand. Met andere woorden, geeft de nieuwsberichten ({pagina} - 1) * {aantal} + 1 tot en met {pagina} * {aantal} terug, waarbij 1 het meest recent toegevoegde bericht is. '
      produces:
      - 'application/json'
      parameters:
      - name: aantal
        in: query
        description: 'Het aantal nieuwsberichten per resultaatpagina.'
        required: false
        default: 15
        type: string
      - name: pagina
        in: query
        description: 'Het paginanummer.'
        required: false
        default: 1
        type: string
      responses:
        200:
            description: 'Success'
            schema:
              type: object
              properties:
                page: 
                  type: integer
                count: 
                  type: integer
                news:
                  type: array
                  items: 
                    $ref: '#/definitions/NewsItem'
        400:
            description: 'Parameter ''aantal'' of ''pagina'' heeft geen geldige waarde.'

  '/nieuws/bericht/{id}':
    get:
      tags:
      - 'nieuws'
      summary: 'Details van een specifiek nieuwsbericht'
      description: 'Geeft de details van een specifiek nieuwsbericht'
      produces:
      - 'application/json'
      parameters:
      - name: id
        in: path
        description: 'Het unieke ID van het nieuwsbericht'
        required: true
        type: integer
      responses:
        200:
            description: 'Success'
            schema:
              $ref: '#/definitions/NewsItem'
        404:
            description: 'ID is ongeldig'

  '/agenda/overzicht[/week]':
    get:
      tags:
      - 'agenda'
      summary: 'Overzicht van alle agendaberichten in de komende 7 dagen'
      description: 'Geeft een overzicht van alle agendaberichten in de komende week'
      produces:
      - 'application/json'
      responses:
        200:
            description: 'Success'
            schema:
              type: array
              items:
                $ref: '#/definitions/AgendaItem'

  '/agenda/overzicht/maand':
    get:
      tags:
      - 'agenda'
      summary: 'Overzicht van alle agendaberichten in de komende 30 dagen'
      description: 'Geeft een overzicht van alle agendaberichten in de komende maand'
      produces:
      - 'application/json'
      responses:
        200:
            description: 'Success'
            schema:
              type: array
              items:
                $ref: '#/definitions/AgendaItem'

  '/agenda/overzicht/alles':
    get:
      tags:
      - 'agenda'
      summary: 'Overzicht van alle agendaberichten in de toekomst'
      description: 'Geeft een overzicht van alle agendaberichten in de toekomst'
      produces:
      - 'application/json'
      responses:
        200:
            description: 'Success'
            schema:
              type: array
              items:
                $ref: '#/definitions/AgendaItem'

  '/agenda/kalender':
    get:
      tags:
      - 'agenda'
      summary: 'Haalt de agenda op in kalender-formaat voor de huidige maand'
      description: 'Geeft alle agendaitems voor de huidige kalendermaand gegroepeerd op dag van de maand.'
      produces:
      - 'application/json'
      responses:
        200:
          description: 'Success'
          schema:
            type: object
            properties:
              items:
                type: array
                items:
                  $ref: '#/definitions/AgendaItem'
              days:
                type: object
                description: 'Eigenschapnamen zijn datum binnen gegeven maand in yyyy-mm-dd formaat'
                additionalProperties:
                  type: array
                  description: 'ID''s van agenda-items op deze datum'
                  items:
                    type: integer
                example:
                  '2017-01-20': [ 40234, 48398 ]
                  '2017-01-21': [ 40234, 47239 ]
                  '2017-01-22': [ 52372 ]

  '/agenda/kalender/{jaar}/{maand}':
    get:
      tags:
      - 'agenda'
      summary: 'Haalt de agenda op in kalender-formaat voor de gegeven maand'
      description: 'Geeft alle agendaitems voor de gegeven kalendermaand gegroepeerd op dag van de maand.'
      produces:
      - 'application/json'
      parameters:
      - name: jaar
        in: path
        description: 'Het jaartal'
        required: true
        type: integer
      - name: maand
        in: path
        description: 'De maand van het jaar (1 - 12)'
        required: true
        type: integer
      responses:
        400:
          description: 'Maand of jaartal ongeldig. Maand moet 1, 2, ..., 12 zijn.'
        200:
          description: 'Success'
          schema:
            type: object
            properties:
              items:
                type: array
                items:
                  $ref: '#/definitions/AgendaItem'
              days:
                type: object
                description: 'Eigenschapnamen zijn datum binnen gegeven maand in yyyy-mm-dd formaat'
                additionalProperties:
                  type: array
                  description: 'ID''s van agenda-items op deze datum'
                  items:
                    type: integer
                example:
                  '2017-01-20': [ 40234, 48398 ]
                  '2017-01-21': [ 40234, 47239 ]
                  '2017-01-22': [ 52372 ]

  '/agenda/details/{id}':
    get:
      tags:
      - 'agenda'
      summary: 'Details van een specifiek agendaitem'
      description: 'Geeft de details van een specifiek agendaitem'
      produces:
      - 'application/json'
      parameters:
      - name: id
        in: path
        description: 'Het unieke ID van het agendabericht'
        required: true
        type: integer
      responses:
        200:
            description: 'Success'
            schema:
              $ref: '#/definitions/AgendaItem'
        404:
            description: 'ID is ongeldig'

  '/podcast/overzicht':
    get:
      tags:
      - 'podcast'
      summary: 'Overzicht van meest recente podcasts'
      description: 'Geeft een overzicht van {aantal} recente podcasts, de meest recente {pagina} pagina''s overslaand. Met andere woorden, geeft de podcasts ({pagina} - 1) * {aantal} + 1 tot en met {pagina} * {aantal} terug, waarbij 1 de meest recent toegevoegde podcast is. '
      parameters:
      - name: aantal
        in: query
        description: 'Het aantal podcasts per resultaatpagina.'
        required: false
        default: 15
        type: string
      - name: pagina
        in: query
        description: 'Het paginanummer.'
        required: false
        default: 1
        type: string
      responses:
        200:
            description: 'Success'
            schema:
              type: object
              properties:
                page: 
                  type: integer
                count: 
                  type: integer
                podcasts:
                  type: array
                  items: 
                    $ref: '#/definitions/Podcast'
        400:
            description: 'Parameter ''aantal'' of ''pagina'' heeft geen geldige waarde.'

  '/podcast/download/{id}/{title}':
    get:
      tags:
      - 'podcast'
      summary: 'Download een specifieke podcast'
      description: 'Geeft een MP3-bestand terug waarvan de headers de browser forceren het bestand te downloaden.'
      produces:
      - 'audio/mpeg'
      parameters:
      - name: id
        in: path
        description: 'Het unieke ID van de podcast'
        required: true
        type: integer
      - name: title
        in: path
        description: 'De titel van de podcast'
        required: true
        type: string
      - name: auth
        in: query
        description: 'De authorisatiecode voor het downloaden van de podcast. Deze verandert per gebruikerssessie. (Dit is onder andere nodig om te voorkomen dat uitzendingen ouder dan twee weken kunnen worden gedownload door de URL aan te passen.) Deze sleutel is beschikbaar via de ''url'' eigenschap van de podcast.'
        required: true
        type: string

        404:
            description: 'Podcast ID of authorisatiesleutel is ongeldig'

  '/podcast/stream/{id}/{title}':
    get:
      tags:
      - 'podcast'
      summary: 'Stream een specifieke podcast'
      description: 'Geeft een MP3-bestand terug voor live streaming'
      produces:
      - 'audio/mpeg'
      parameters:
      - name: id
        in: path
        description: 'Het unieke ID van de podcast'
        required: true
        type: integer
      - name: title
        in: path
        description: 'De titel van de podcast'
        required: true
        type: string
      - name: auth
        in: query
        description: 'De authorisatiecode voor het streamen van de podcast. Deze verandert per gebruikerssessie. (Dit is onder andere nodig om te voorkomen dat uitzendingen ouder dan twee weken kunnen worden gestreamd door de URL aan te passen.) Deze sleutel is beschikbaar via de ''url'' eigenschap van de podcast.'
        required: true
        type: string

        404:
            description: 'Podcast ID of authorisatiesleutel is ongeldig'

  '/programma/schema/nustraks':
    get:
      tags:
      - 'programma'
      summary: 'Programmas nu en straks'
      description: 'Geeft een overzicht van de programmas in de komende 24 tot 48 uur. Let op: van de programmas zijn de podcasts en het uitzendschema niet ingevuld.'
      responses:
        200:
            description: 'Success'
            schema:
              type: object
              properties:
                startdate:  
                  $ref: '#/definitions/DateTime'
                enddate:  
                  $ref: '#/definitions/DateTime'
                schedule:
                  type: array
                  items:
                    type: object
                    properties: 
                      time:
                        $ref: '#/definitions/DateTime'
                      program:
                        $ref: '#/definitions/Program'
                errors:
                  type: array 
                  items:
                    type: string

  '/programma/schema/week':
    get:
      tags:
      - 'programma'
      summary: 'Programmaschema van de huidige week'
      description: 'Geeft een overzicht van de programmas in de huidige week. De week begint op maandag.'
      responses:
        200:
            description: 'Success'
            schema:
              type: object
              properties:
                startdate:  
                  $ref: '#/definitions/DateTime'
                enddate:  
                  $ref: '#/definitions/DateTime'
                schedule:
                  type: array
                  items:
                    type: object
                    properties: 
                      time:
                        $ref: '#/definitions/DateTime'
                      program:
                        $ref: '#/definitions/Program'
                errors:
                  type: array 
                  items:
                    type: string

  '/programma/schema/week/{weken}':
    get:
      tags:
      - 'programma'
      summary: 'Programmaschema van de huidige week en één of meer weken vooruit'
      description: 'Geeft een overzicht van de programmas voor een aantal weken vooruit, beginnend op maandag van de huidige week.'
      parameters:
      - name: weken
        in: path
        description: 'Het aantal op te vragen weken'
        required: true
        type: integer
      responses:
        400:
            description: 'Parameter ''weken'' heeft geen geldige waarde.'
        200:
            description: 'Success'
            schema:
              type: object
              properties:
                startdate:  
                  $ref: '#/definitions/DateTime'
                enddate:  
                  $ref: '#/definitions/DateTime'
                schedule:
                  type: array
                  items:
                    type: object
                    properties: 
                      time:
                        $ref: '#/definitions/DateTime'
                      program:
                        $ref: '#/definitions/Program'
                errors:
                  type: array 
                  items:
                    type: string

#securityDefinitions:
  #petstore_auth:
  #  type: 'oauth2'
  #  authorizationUrl: 'http://petstore.swagger.io/oauth/dialog'
  #  flow: 'implicit'
  #  scopes:
  #    write:pets: 'modify pets in your account'
  #    read:pets: 'read your pets'
  #api_key:
  #  type: 'apiKey'
  #  name: 'api_key'
  #  in: 'header'
definitions:
  DateTime:
    type: object
    properties:
      date:
        type: string
        format: 'yyyy-mm-dd hh:mm:ss.zzzzzz'
        example: '2017-07-12 15:23:59.000000'
      timezone_type:
        type: integer
        example: 4
      timezone:
        type: string
        example: 'Europe/Amsterdam'
  NewsSource:
    type: object
    properties:
      title:
        type: string
      url:
        type: string
      show:
        type: 'boolean'
  NewsImage:
    type: object
    properties:
      id:
        type: integer
      title:
        type: string
      url:
        type: string

  NewsItem:
    type: object
    properties:
      id:
        type: integer
      title:
        type: string
      content:
        type: string
      published:
        $ref: '#/definitions/DateTime'
      edited:
        $ref: '#/definitions/DateTime'
      keywords:
        type: array
        items:
          type: string
      source:
        type: array
        items:
          $ref: '#/definitions/NewsSource'
      theme:
        type: string
      region:
        type: string
      podcast:
        type: string
      images:
        type: array
        items:
          $ref: '#/definitions/NewsImage'
      video:
        type: string
      url:
        type: string

  AgendaItem:
    type: object
    properties:
      id:
        type: integer
      title:
        type: string
      region:
        type: string
      content:
        type: string
      starts:
        $ref: '#/definitions/DateTime'
      ends:
        $ref: '#/definitions/DateTime'
      images:
        type: array
        items:
          $ref: '#/definitions/NewsImage'
      url:
        type: string

  Podcast:
    type: object
    properties:
      id:
        type: integer
      title:
        type: string
      content:
        type: string
      created:
        $ref: '#/definitions/DateTime'
      program:
        $ref: '#/definitions/Program'
        description: 'Alleen de {name}, {description} en {id} van het programma worden ingevuld, {hosts}, {schedule} en {podcasts} zijn leeg. Gebruik GET /programma om meer informatie hierover te krijgen.'
      url:
        type: string
        description: 'Link om de podcast als MP3 te streamen of te downloaden. Voeg hiervoor /podcast/stream/ of /podcast/download/ toe voor de url, bijvoorbeeld: /podcast/stream/213723/6fm-podcast-titel-slug?auth=15ff823563323fe3342812937b4013984218'

  Program: 
    type: object
    properties:
      id:
        type: integer
      name:
        type: string
      description:
        type: string
      email:
        type: string
        description: 'Het (hoofd)mailadres van het programma, zonder @6fm.nl'
        example: 'vroegeroflater'
      hosts:
        type: array
        items:
          $ref: '#/definitions/ProgramHost'
        required: false
      listenagain:
        type: array
        description: 'NOT IMPLEMENTED YET!'
        required: false
      next:
        type: string
        description: 'NOT IMPLEMENTED YET!'
        required: false

  ProgramHost:
    type: object
    properties:
      id:
        type: integer
      name:
        type: string
      email:
        type: string
        description: 'Het (hoofd)mailadres van de gebruiker, zonder @6fm.nl. (Verwacht maximaal één adres met preference 0).'

#externalDocs:
#  description: 'Find out more about Swagger'
#  url: 'http://swagger.io'
