# Kalliópê Massive Intyeraction suite
# as a demonstration of an API spec in YAML
swagger: '2.0'
info:
  title: Kalliópê API
  description: Spatial storytelling is about to change
  version: "1.0.0"
# the domain of the service
host: orion.iglor.es:4567
# array of all schemes that your API supports
schemes:
  - http
# will be prefixed to all paths
basePath: /v1
produces:
  - application/json
paths:

  # OWNER
  # TODO: Identiy Kallíope owner / Licence system?

  # PROJECTS
  
  /projects:
    get:
      summary: Returns projects List
      description: |
        This query returns a list of the projects associated to the user on the server. The response includes the name of the project, a short description and the server type.
      tags:
        - Projects
      responses:
        200:
          description: An array of projects
          schema:
            type: array
            items:
              $ref: '#/definitions/Project'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
            
  /projects/new:
   post:
      summary: Creates a new project
      description: |
        Creates a new project on the server.
      parameters:
        - name: name
          in: query
          description: Desired name of the project.
          required: true
          type: string
        - name: description
          in: query
          description: Short description about the project.
          required: false
          type: string
        - name: servertype
          in: query
          description: Server Type used by the project.
          required: true
          type: string
      tags:
        - Projects
      responses:
        200:
          description: Project created
          schema:
            $ref: '#/definitions/Success'
        409:
          description: Project name already used
          schema:
            $ref: '#/definitions/Conflict'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
            
  /projects/modify:
    put:
      summary: Modify project
      description: |
        Modifies project information on server.
      parameters:
        - name: name
          in: query
          description: Desired name of the project.
          required: true
          type: string
        - name: description
          in: query
          description: Short description about the project.
          required: false
          type: string
        - name: servertype
          in: query
          description: Server Type used by the project.
          required: true
          type: string
      tags:
        - Projects
      responses:
        200:
          description: Project updated
          schema:
            $ref: '#/definitions/Success'
        409:
          description: Project name already used
          schema:
            $ref: '#/definitions/Conflict'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  
  /projects/delete:
    delete:
      summary: Delete project
      description: |
        Deletes project from server.
      parameters:
        - name: name
          in: query
          description: Desired name of the project.
          required: true
          type: string
      tags:
        - Projects
      responses:
        200:
          description: Project deleted
          schema:
            $ref: '#/definitions/Success'
        404:
          description: Project not found
          schema:
            $ref: '#/definitions/NotFound'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
            
  #UPLOAD CONTENT
  /media:
     get:
      summary: Returns file List
      description: |
        This query returns a list of the files associated to a project. 
      parameters:
        - $ref: "#/parameters/projectIdParam"
      tags:
        - Projects
      responses:
        200:
          description: An array of files
          schema:
            type: array
            items:
              $ref: '#/definitions/Project'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  /media/upload:
   post:
      summary: Upload a new media
      description: |
        Upload a new media associated with a given project.
      parameters:
        - $ref: "#/parameters/projectIdParam"
        - name: media
          in: formData
          description: The file sent
          required: true
          type: file
      tags:
        - Projects
      responses:
        200:
          description: Media uploade successful
          schema:
            $ref: '#/definitions/Success'
        409:
          description: Media already exist
          schema:
            $ref: '#/definitions/Conflict'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  # PUBLIC USERS
  
  /public/new:
   post:
      summary: Creates public user
      description: |
        Create a new public user associated with a project on server.
      parameters:
        - $ref: "#/parameters/clientIdParam"
        - $ref: "#/parameters/clientTypeParam"
        - $ref: "#/parameters/projectIdParam"
        - $ref: "#/parameters/hardwareInfoParam"
        - $ref: "#/parameters/osInfoParam"
      tags:
        - Public Users
      responses:
        200:
          description: Project created
          schema:
            $ref: '#/definitions/Success'
        409:
          description: Client ID already used
          schema:
            $ref: '#/definitions/Conflict'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
            
  /public/modify:
    put:
      summary: Modify user
      description: |
        Modifies profile information about the user.
      parameters:
        - $ref: "#/parameters/clientIdParam"
        - $ref: "#/parameters/projectIdParam"
        - $ref: "#/parameters/hardwareInfoParam"
        - $ref: "#/parameters/osInfoParam"
        # User profile related
        - $ref: "#/parameters/firstNameParam"
        - $ref: "#/parameters/lastNameParam"
        - $ref: "#/parameters/genderParam"
        - $ref: "#/parameters/ageParam"
        - $ref: "#/parameters/countryParam"
        - $ref: "#/parameters/languageParam"
        - $ref: "#/parameters/emailParam"
        - $ref: "#/parameters/phoneParam"
        - $ref: "#/parameters/pictureParam"
      tags:
        - Public Users
      responses:
        200:
          description: User updated
          schema:
            $ref: '#/definitions/Success'
        404:
          description: User not found
          schema:
            $ref: '#/definitions/NotFound'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  
  /public/delete:
    delete:
      summary: Delete a user
      description: |
        Deletes a user from server.
      parameters:
        - $ref: "#/parameters/clientIdParam"
        - $ref: "#/parameters/projectIdParam"
      tags:
        - Public Users
      responses:
        200:
          description: User deleted
          schema:
            $ref: '#/definitions/Success'
        404:
          description: User not found
          schema:
            $ref: '#/definitions/NotFound'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'

  /public/user:
    get:
      summary: Public User Profile
      description: The User Profile endpoint returns information about the public user that is using one of the public client apps.
      parameters:
        - name: uuid
          in: query
          description: User unique identifier.
          required: true
          type: string
      tags:
        - Public Users
      responses:
        200:
          description: Profile information for a user
          schema:
            $ref: '#/definitions/PublicUserProfile'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  /public/group:
    get:
      summary: Group assignation 
      description: Returns a group to the user according to rules specified on the server side
      parameters:
        - name: profile
          in: body
          required: true
          schema:
            $ref: '#/definitions/PublicUserProfile'
      tags:
        - Public Users
      responses:
        200:
          description: Assigned group
          schema:
            $ref: '#/definitions/Group'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
      
  /public/history:
    get:
      summary: Public User Activity
      description: The User Activity endpoint returns data about a user's lifetime activity with Kalliópê. The response will include geolocations and times, multimedia content accesed, information about which actions where taken, etc...<br><br>The history array in the response will have a maximum length based on the limit parameter. The response value count may exceed limit, therefore subsequent API requests may be necessary.
      parameters:
        - $ref: "#/parameters/projectIdParam"
        - name: uuid
          in: query
          description: Filter user by user uuid. If not all users are returned.
          required: false
          type: string
        - name: activity_description
          in: query
          description: Filter user by activity_description.
          required: false
          type: string
        - name: offset
          in: query
          type: integer
          format: int32
          description: Offset the list of returned results by this amount. Default is zero.
        - name: limit
          in: query
          type: integer
          format: int32
          description: Number of items to retrieve. Default is 5, maximum is 100.
      tags:
        - Public Users
      responses:
        200:
          description: History information for the given user
          schema:
            $ref: '#/definitions/Activities'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  
  #TODO: Define activities: QUIZ, GEOPOSITION, etc..
  /public/upload/activity:
    post:
      summary: Upload Activity
      description: The user sends an activity to the server.
      parameters:
        - $ref: "#/parameters/clientIdParam"
        - $ref: "#/parameters/projectIdParam"
        - $ref: "#/parameters/clientTypeParam"
        - name: description
          in: query
          description: Activity Type
          required: true
          type: string
        - name: data
          in: query
          description: JSON data related to the activity.
          required: true
          type: string
      tags:
        - Public Users
      responses:
        200:
          description: Activity archived
          schema:
            $ref: '#/definitions/Success'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  
  /public/upload/file:
    post:
      summary: Upload file
      description: The user sends a media file to the serverc ontaining a multimedia element.
      parameters:
        - $ref: "#/parameters/clientIdParam"
        - $ref: "#/parameters/projectIdParam"
        - name: media
          in: formData
          description: The file sent
          required: true
          type: file
      tags:
        - Public Users
      responses:
        200:
          description: File uploaded
          schema:
            $ref: '#/definitions/Success'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'

# define models:
definitions:
  Project:
    properties:
      name:
        type: string
        description: Unique identifier representing a project.
      description:
        type: string
        description: Description of the project.
      servertype:
        type: string
        description: Server type the project is using (Ej. ORION or MOSQUITTO).
  Group: 
    type: object
    properties:
      group:
        type: string
        description: Assigned group
  PublicUserProfile:
    type: object
    properties:
      uuid:
        type: string
        description: Unique identifier for the user.
      project:
        type: string
        description: Name of the project the app is connected to.
      hardware:
        type: string
        description: Hardware in wich the Public App is installed.
      so:
        type: string
        description: Operating system where Public App is installed.
      first_name:
        type: string
        description: First name of the Public user.
      last_name:
        type: string
        description: Last name of the Public user.
      gender:
        type: string
        description: Gender of the Public user.
      age:
        type: integer
        format: int32
        description: Age of the Public user.
      country:
        type: string
        description: Country of the Public user.
      language:
        type: string
        description: Language of the Public user.
      email:
        type: string
        description: Email address of the Public user
      phone:
        type: string
        description: Phone number of the Public user
      picture:
        type: string
        description: Image URL of the Public user.
  Activity:
    properties:
      type:
        type: string
        description: Activity type
      description:
        type: string
        description: Description of the activity
      data:
        type: string
        description: JSON Data generated by the activity
      user_type:
        type: string
        description: User type
      uuid:
        type: string
        description: Unique identifier for the user
      project:
        type: string
        description: Name of the project the app is connected to
      time_stamp:
        type: string
        format: date-time
        description: Whend did the actity happend
  Activities:
    properties:
      offset:
        type: integer
        format: int32
        description: Position in pagination.
      limit:
        type: integer
        format: int32
        description: Number of items to retrieve (100 max).
      count:
        type: integer
        format: int32
        description: Total number of items available.
      history:
        type: array
        items:
          $ref: '#/definitions/Activity'
  Success:
    properties:
      code:
        type: integer
        format: int32
      message:
        type: string
      fields:
        type: string
  Conflict:
    properties:
      code:
        type: integer
        format: int32
      message:
        type: string
      fields:
        type: string
  NotFound:
    properties:
      code:
        type: integer
        format: int32
      message:
        type: string
      fields:
        type: string
  Error:
    properties:
      code:
        type: integer
        format: int32
      message:
        type: string
      fields:
        type: string
        
        
# define reusable parameters:
parameters:
  clientIdParam:
      name: uuid
      in: query
      description: Name of the user.
      required: true
      type: string
  clientTypeParam:
      name: type
      in: query
      description: Client type.
      required: true
      type: string
  projectIdParam:
      name: project
      in: query
      description: Name of the project.
      required: true
      type: string
  hardwareInfoParam:
      name: hardware
      in: query
      description: Hardware in wich the Public App is installed.
      required: false
      type: string
  osInfoParam:
      name: os
      in: query
      description: Operating System in wich the Public App is installed.
      required: false
      type: string
  firstNameParam:
      name: first_name
      in: query
      description: Public User first name or nickname.
      required: false
      type: string
  lastNameParam:
      name: last_name
      in: query
      description: Public User last name or middlename.
      required: false
      type: string
  genderParam:
      name: gender
      in: query
      description: Public User gender.
      required: false
      type: string
  ageParam:
      name: age
      in: query
      description: Public User age.
      required: false
      type: integer
      format: int32
  countryParam:
      name: country
      in: query
      description: Public User country code.
      required: false
      type: string
  languageParam:
      name: language
      in: query
      description: Public User system default language.
      required: false
      type: string
  emailParam:
      name: email
      in: query
      description: Public User email.
      required: false
      type: string
  phoneParam:
      name: phone
      in: query
      description: Public User phone.
      required: false
      type: string
  pictureParam:
      name: picture
      in: query
      description: Public User picture.
      required: false
      type: string
  
  
  
  
  
  
  
