openapi.yaml

openapi: 3.0.0
servers:
  - description: Server which hosts the API
    url: https://congresotryit.es
info:
  description: Official API for the Try IT! congress' website
  version: "1.0.2"
  title: Try IT! API
  contact:
    email: tic.etsiinf@daupm.es
  license:
    name: Apache 2.0
    url: "http://www.apache.org/licenses/LICENSE-2.0.html"
tags:
  - name: Home
    description: General Information required at any given page within the website.
  - name: Editions
    description: Information regarding specific editions.
  - name: Tickets
    description: Information regarding the generation and checking of tickets.
  - name: Awards
    description: Information regarding the different awards.
  - name: Attendance
    description: Information regarding attendance.

paths:
  /streaming:
    get:
      tags:
        - Home
      summary: Returns a JSON object with streaming information.
      operationId: getStreaming
      description: |
        Returns information regarding current streaming status. If the congress is currently streaming, retrieves the url of the livestream.
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StreamingResource"
        "204":
          description: Livestream not currently available.

  /editions:
    get:
      tags:
        - Editions
      summary: Returns a JSON object with all editions
      operationId: getEditions
      description: |
        Returns a JSON object with all editions.
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EditionsResource"

  /editions/{year}:
    get:
      tags:
        - Editions
      summary: Returns a JSON object with info about a specific edition.
      operationId: getYearEdition
      description: |
        Returns a JSON object with information regarding a specific edition
      parameters:
      - in: path
        name: year
        description: Year of the edition
        required: true
        schema:
          type: integer
          example: 2020
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/YearResource"

  /editions/{year}/sponsors:
    get:
      tags:
        - Editions
      summary: Returns a JSON object with all sponsors (companies/organizations) for the specified edition
      operationId: getSponsors
      description: |
        Returns the information of all sponsors for the specified edition. Sponsors will be classified by the type of sponsorship.
      parameters:
        - in: path
          name: year
          description: Year of the edition
          required: true
          schema:
            type: integer
            example: 2020
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SponsorsResource"
  
  /editions/{year}/speakers/:
    get:
      tags:
        - Editions
      summary: Returns a JSON object with all speakers for the specified edition
      operationId: getSpeakers
      description: |
        Returns the information of all speakers (people) of a specific edition. 
      parameters:
        - in: path
          name: year
          description: Year of the edition
          required: true
          schema:
            type: integer
            example: 2020
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SponsorsResource"
  
  /editions/{year}/talks:
    get:
      tags:
        - Editions
      summary: Returns a JSON object with all the talks
      operationId: getTalks
      description: |
        Returns the information of the talks
      parameters:
        - in: path
          name: year
          description: Year of the edition
          required: true
          schema:
            type: integer
            example: 2020
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/TalkResource"

  /editions/{year}/workshops:
    get:
      tags:
        - Editions
      summary: Returns a JSON object with all the workshops
      operationId: getWorkshops
      description: |
        Returns the information of the workshops
      parameters:
        - in: path
          name: year
          description: Year of the edition
          required: true
          schema:
            type: integer
            example: 2020
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/WorkshopResource"

  /editions/{year}/schedule:
    get:
      tags:
        - Editions
      summary: Returns a schedule with all the events in the specified edition
      operationId: getEvents
      description: |
        Returns a schedule with all the events in the given edition.
      parameters:
        - in: path
          name: year
          description: Year of the edition
          required: true
          schema:
            type: integer
            example: 2020
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ScheduleResource"
                
  /editions/{year}/organizers:
    get:
      tags:
        - Editions
      summary: Returns the list of all the organizers
      operationId: getOrganizers
      description: |
        Returns the list of all the organizers
      parameters:
        - in: path
          name: year
          description: Year of the edition
          required: true
          schema:
            type: integer
            example: 2020
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/OrganizerResource"

  /editions/{year}/ects/{nif}:
    get:
      tags:
        - Editions
      summary: Returns the amount of ECTS a student obtains
      operationId: getECTS
      description: |
        Returns the list of all the organizers
      parameters:
        - in: path
          name: year
          description: Year of the edition
          required: true
          schema:
            type: integer
            example: 2020
        - in: path
          name: nif
          description: NIF of the student
          required: true
          schema:
            type: string
            example: X255555T
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: number
                example: 1.5
  
  /tickets:
      post:
        tags:
          - Tickets
        summary: Creates a new ticket
        operationId: postTicket
        description: |
          Sends the information of the form filled by the user to the server in order to create a new ticket and send him the email with the ticket. It also generates information regarding the distribution.
        requestBody:
          required: true
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TicketResource"
        responses:
          "201":
            description: OK
            content:
              application/json:
                schema:
                  $ref: "#/components/schemas/PostSuccessResource"

  /tickets/{ticket_id}/distribution:
      get:
        tags:
          - Tickets
        summary: Gets the assigned location distribution for an attendee for a specific ticket. 
        operationId: getDistribution
        description: |
          Returns the different locations (rooms / classes) to which the attendee is asigned. For example, the student has to go to room "SALON DE ACTOS" on day 1 or "5001" on day 2.
        parameters:
          - in: path
            name: ticket_id
            description: ID of the Ticket
            required: true
            schema:
              type: integer
              example: 75
        responses:
          "200":
            description: OK
            content:
              application/json:
                schema:
                  type: array
                  items:
                    $ref: "#/components/schemas/LocationResource"

  /prizes:
      get:
        tags:
          - Awards
        summary: From a specified prize scenario, returns an attendee's NIF. (INFO - SENDING ENTIRE PRIZERESOURCE BUT THAT IS NOT NECESSARY)
        operationId: getPrize
        description: |
          It generates a winner for the specified raffle. If a prize is selected, it uses that one. Otherwise (no request body json object), it chooses a random one from a pre-established pool of prizes.
        parameters:
          - in: query
            name: is_global_raffle
            description: If false, it indicates that the raffle is for a single event (talk, workshop, ...). If true, it indicates that it has to take into consideration the assistance to all events in the congress.
            required: true
            schema:
              type: boolean
              example: false
        requestBody:
          required: false
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PrizeResource"
        responses:
          "200":
            description: OK
            content:
              application/json:
                schema:
                  type: string
                  example: 12345678A

  /attendance:
      post:
        tags:
          - Attendance
        summary: Sends necessary information to register a user's attendance
        operationId: postValidation
        description: |
          Sends the information in order to check attendance.
        requestBody:
          required: true
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AttendanceResource"
        responses:
          "200":
            description: OK
            content:
              application/json:
                schema:
                  $ref: "#/components/schemas/PostSuccessResource"

components:
  schemas:
    EditionsResource:
      type: array
      items:
        type: object
        required:
          - id
          - year
          - title
          - slogan
          - description
          - start_date
          - end_date
          - google_calendar_url
        properties:
          id:
            $ref: "#/components/schemas/IdResource"
          year:
            type: integer
            example: 2020
          title:
            type: string
            example: Try IT! 2020
          slogan:
            type: string
          description:
            type: string
          start_date:
            $ref: "#/components/schemas/DateResource"
          end_date:
            $ref: "#/components/schemas/DateResource"
          google_calendar_url:
            type: string
            pattern: http[s]?:\/\/(?:[a-zA-Z]|[0-9]|[\/.?&+!*=\-])+(?![^,!;:\s)])
            format: url

    YearResource:
      type: object
      required:
        - id
        - year
        - title
        - slogan
        - description
        - start_date
        - end_date
        - google_calendar_url
      properties:
        id:
          $ref: "#/components/schemas/IdResource"
        year:
          type: integer
          example: 2020
        title:
          type: string
          example: Try IT! 2020
        slogan:
          type: string
        description:
          type: string
        start_date:
          $ref: "#/components/schemas/DateResource"
        end_date:
          $ref: "#/components/schemas/DateResource"
        google_calendar_url:
          type: string
          pattern: http[s]?:\/\/(?:[a-zA-Z]|[0-9]|[\/.?&+!*=\-])+(?![^,!;:\s)])
          format: url

    # TICKET
    TicketResource:
      type: object
      required:
        - name
        - lastname
        - identity
        - email
        - is_student
        - phone
      properties:
        name:
          type: string
          example: Iron Man
        lastname:
          type: string
          example: The Best
        identity:
          type: string
          pattern: "[/^[0-9]{8}[TRWAGMYFPDXBNJZSQVHLCKET]{1}$/|/^[XYZ]{1}[0-9]{7}[TRWAGMYFPDXBNJZSQVHLCKET]{1}$/]"
          example: 00112233K (DNI) or X0011223T (NIE)
        email:
          type: string
          format: email
          example: contact@ironman.com
        is_student:
          type: boolean
          example: true
        is_upm_student:
          type: boolean
          example: true
        upm_school:
          type: string
          example: ETSIINF
        degree:
          type: string
          example: Grado en Ingeniería de Armas Nucleares
        year:
          type: integer
          minimum: 1
          maximum: 4
          example: 2
        phone:
          type: string
          example: "123456789"
    # END TICKET

    InvalidTicketResource:
      type: object
      required:
        - status
        - message
      properties:
        status:
          type: integer
          minimum: 400
          maximum: 400
          example: 400
        string:
          type: string
          example: The user must have a ticket for the current edition

    DateResource:
      type: integer
      example: 1581089789382

    IdResource:
      type: integer
      example: 812

    StreamingResource:
      type: object
      required:
        - title
        - url
        - streaming
      properties:
        talk:
          $ref: "#/components/schemas/TalkResource"
        url:
          type: string
          pattern: http[s]?:\/\/(?:[a-zA-Z]|[0-9]|[\/.?&+!*=\-])+(?![^,!;:\s)])
          format: url
          example: "https://www.twitch.tv/tryit_upm"

    # SPEAKER
    SpeakerResource:
      type: object
      required:
        - name
        - image
        - bio
        - organization
      properties:
        name:
          type: string
          example: Victor Nieves
        bio:
          type: string
          example: No one knows where he was born
        image:
          type: string
          pattern: http[s]?:\/\/(?:[a-zA-Z]|[0-9]|[\/.?&+!*=\-])+(?![^,!;:\s)])
          format: url
          example: "https://www.images.com/victor"
        web:
          type: string
          pattern: http[s]?:\/\/(?:[a-zA-Z]|[0-9]|[\/.?&+!*=\-])+(?![^,!;:\s)])
          format: url
          example: "https://www.personalweb.com/"
        organization:
          $ref: "#/components/schemas/OrganizerResource"
        social_media:
          type: object
          properties:
            twitter:
              type: string
              pattern: http[s]?:\/\/(?:[a-zA-Z]|[0-9]|[\/.?&+!*=\-])+(?![^,!;:\s)])
              format: url
              example: "https://twitter.com/IronMan"
            facebook:
              type: string
              pattern: http[s]?:\/\/(?:[a-zA-Z]|[0-9]|[\/.?&+!*=\-])+(?![^,!;:\s)])
              format: url
              example: "https://facebook.com/IronMan"
            linkedin:
              type: string
              pattern: http[s]?:\/\/(?:[a-zA-Z]|[0-9]|[\/.?&+!*=\-])+(?![^,!;:\s)])
              format: url
              example: "https://linkedin.com/IronMan"
            github:
              type: string
              pattern: http[s]?:\/\/(?:[a-zA-Z]|[0-9]|[\/.?&+!*=\-])+(?![^,!;:\s)])
              format: url
              example: "https://github.com/IronMan"
            gitlab:
              type: string
              pattern: http[s]?:\/\/(?:[a-zA-Z]|[0-9]|[\/.?&+!*=\-])+(?![^,!;:\s)])
              format: url
              example: "https://gitlab.com/IronMan"
    # END SPEAKER
    ScheduleResource:
      type: array
      items:
        type: object
        required:
          - id
          - name
          - description
          - eventtype
        properties:
          id:
            $ref: "#/components/schemas/IdResource"
          name:
            type: string
            example: Awesome name
          description:
            type: string
            example: Awesome description
          eventtype:
            type: string
            pattern: "talk | workshop | activity"
            example: talk


     # Event
    EventResource:
      type: object
      required:
        - id
        - name
        - description
        - eventtype
      properties:
        id:
          $ref: "#/components/schemas/IdResource"
        name:
          type: string
          example: Awesome name
        description:
          type: string
          example: Awesome description
        eventtype:
          type: string
          pattern: "talk | workshop | activity"
          example: talk
    
    ActivityResource:
      type: object
      required:
        - event
        - image
        - poster
        - registration
      properties:
        event:
          $ref: "#/components/schemas/EventResource"
        image:
          type: string
          pattern: http[s]?:\/\/(?:[a-zA-Z]|[0-9]|[\/.?&+!*=\-])+(?![^,!;:\s)])
          format: url
          example: "https://www.image.com/"
        poster:
          type: string
          pattern: http[s]?:\/\/(?:[a-zA-Z]|[0-9]|[\/.?&+!*=\-])+(?![^,!;:\s)])
          format: url
          example: "https://www.image.com/"
        registration:
          type: boolean
          example: True

    # TALKS
    TalkResource:
      type: object
      required:
        - event
        - url
        - video
        - start_date
        - end_date
        - slide
        - room
        - speaker
      properties:
        event:
          $ref: "#/components/schemas/EventResource"
        url:
          type: string
          format: url
          pattern: http[s]?:\/\/(?:[a-zA-Z]|[0-9]|[\/.?&+!*=\-])+(?![^,!;:\s)])
          example: "https://www.ted.com/talks/captain_america_TED_talk"
        video:
          type: string
          format: url
          pattern: http[s]?:\/\/(?:[a-zA-Z]|[0-9]|[\/.?&+!*=\-])+(?![^,!;:\s)])
          example: "https://www.youtube.com/watch?v=ANOTHERONE"
        start_date:
          $ref: "#/components/schemas/DateResource"
        end_date:
          $ref: "#/components/schemas/DateResource"
        slide:
          type: string # VERIFY
          format: url
          pattern: http[s]?:\/\/(?:[a-zA-Z]|[0-9]|[\/.?&+!*=\-])+(?![^,!;:\s)])
          example: "https://slide_url.com"
        room:
          type: string
          example: dark room
        speakers:
          type: array
          items:
            $ref: "#/components/schemas/SpeakerResource"
    # END TALKS

    # WORKSHOPS
    WorkshopResource:
      type: object
      required:
        - event
        - speakers
        - room
        - date
      properties:
        event:
          $ref: "#/components/schemas/EventResource"
        speakers:
          type: array
          items:
            $ref: "#/components/schemas/SpeakerResource"
        room:
          type: string
          example: Wellington or Peralta
        date:
          $ref: "#/components/schemas/DateResource"
    # END WORKSHOPS

    # PRIZE
    PrizeResource:
      type: object
      required:
        - name
        - description
        - image
        - value
      properties:
        name:
          type: string
          example: Minttu
        description:
          type: string
          example: One full bottle of Minttu
        image:
          type: string
          pattern: http[s]?:\/\/(?:[a-zA-Z]|[0-9]|[\/.?&+!*=\-])+(?![^,!;:\s)])
          format: url
          example: "https://www.images.com/iron_man"
        value:
          type: number
          example: 199.99
    # END PRIZE

    # SPONSORS
    SponsorsResource:
      type: array
      items:
        type: object
        required:
          - category
          - sponsors
        properties:
          category:
            type: string
            pattern: "stand | stand-vip | oro | diamante"
            example: diamante
          sponsors:
            type: array
            items:
              $ref: "#/components/schemas/SponsorResource"

    SponsorResource:
      type: object
      required:
        - name
        - logo
        - url
      properties:
        name:
          type: string
          example: Avengers Endgame
        logo:
          type: object
          required:
            - image
            - url
          properties:
            source:
              type: string
              pattern: http[s]?:\/\/(?:[a-zA-Z]|[0-9]|[\/.?&+!*=\-])+(?![^,!;:\s)])
              format: url
              example: "https://www.images.com/iron_man"
        url:
          type: string
          pattern: http[s]?:\/\/(?:[a-zA-Z]|[0-9]|[\/.?&+!*=\-])+(?![^,!;:\s)])
          format: url
          example: "https://www.organization.com/"
    # END SPONSORS

    AttendanceResource:
      type: object
      required:
        - session_id
        - ticket_id
        - ticket_signature
        - signature
        - time_stamp
      properties:
        session_id:
          type: integer
          example: 42
        ticket_id:
          type: integer
          example: 75
        ticket_signature:
          type: string
          example: KFSDHJF8232L
        signature:
          type: string
          example: RE34TGFDS
        time_stamp:
          type: integer
          example: 234213414123
    
    LocationResource:
      type: object
      required:
        - days
        - rooms
        - ticket_id
      properties:
        days:
          type: array
          items:
            type: integer
            example: 1
        rooms:
          type: array
          items:
            type: string
            example: "Salon de Actos"
        ticket_id:
          type: integer
          example: 75

    OrganizerResource:
      required:
        - name
        - description
        - email
        - role
        - image
      properties:
        name:
          type: string
          example: Iron man
        description:
          type: string
          example: Best superhero ever
        email:
          type: string
          format: email
          example: contact@ironman.com
        role:
          type: string
          example: It is the boss
        image:
          type: string
          pattern: http[s]?:\/\/(?:[a-zA-Z]|[0-9]|[\/.?&+!*=\-])+(?![^,!;:\s)])
          format: url
          example: "https://www.image.com/"

    PostSuccessResource:
      type: object
      required:
        - code
        - message
        - message_abbr
      properties:
        code:
          type: integer
          example: 12
        message:
          type: string
          example: "Ticket creado correctamente"
        message_abbr:
          type: string
          example: "ticket_post_success // See messages abbreviations"