# 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: /v2
produces:
  - application/json
paths:
  /projects:
    get:
      summary: Returns projects List
      description: |
        This query returns a list of the projects 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'
    post:
      summary: Creates a new project. Duplicates are not allowed
      description: |
        Creates a new project on the server.
      parameters:
        - name: name
          in: body
          description: Required data to create a project
          required: true
          schema:
              $ref: '#/definitions/Project'
      tags:
        - Projects
      responses:
        200:
          description: Project created.
        409:
          description: Project name already used
          schema:
            $ref: '#/definitions/Conflict'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
    put:
      summary: Modify project 
      description: |
        Modifies project information on server. All parameters are required
      parameters: #All the related data to the project is needed for the update?? 'put' implies this if not use patch
        - name: name
          in: body
          description: Desired name of the project.
          required: true
          schema:
            $ref: '#/definitions/Project'
      tags:
        - Projects
      responses:
        200:
          description: Project updated
        400:
          description: Invalid project name
          schema:
            $ref: '#/definitions/Error'
        404:
          description: Project not found
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  /projects/{name}:
    get:
      summary: Find a project by name
      description: |
        Return the project info. Name is required
      parameters:
        - name: name
          in: path
          description: Name of the project to fetch
          required: true
          type: string
      tags:
        - Projects
      responses:
        200:
          description: Project returned
          schema:
            $ref: '#/definitions/Project'
        404:
          description: Project not found
          schema:
            $ref: '#/definitions/NotFound'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
    delete:
      summary: Delete project
      description: |
        Deletes project from server. Name is required
      parameters:
        - name: name
          in: path
          description: Name of the project to delete
          required: true
          type: string
      tags:
        - Projects
      responses:
        200:
          description: Project deleted
        404:
          description: Project not found
          schema:
            $ref: '#/definitions/NotFound'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  /media:
    get:
      summary: Returns file List
      description: |
        This query returns a list of the files associated to a project. 
      tags:
        - Media
      responses:
        200:
          description: An array of files
          schema:
            type: array
            items:
              $ref: '#/definitions/Media'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
    post:
      summary: Upload a new media
      description: |
        Upload a new media associated with a given project.
      consumes:
        - application/x-www-form-urlencoded
      parameters:
        - name: file
          in: formData
          description: File data
          required: true
          type: file
        - name: project
          in: formData
          required: true
          type: string
          description: Project name owner
        - name: md5sum
          in: formData
          required: true
          type: string
          description: sha1 code for integrity checks and control version
      tags:
        - Media
      responses:
        200:
          description: File data stored
          schema:
            type: array
            items:
              $ref: '#/definitions/Media'
        409:
          description: Media already exist
          schema:
            $ref: '#/definitions/Conflict'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  /public:
    post:
      summary: Creates a new user. 
      description: |
        Creates a new user. Duplicates are not allowed. uuid, type and project are required
      tags:
        - Public Users
      parameters:
        - name: name
          in: body
          description: Required data to create an user
          required: true
          schema:
              $ref: '#/definitions/PublicUserProfile'
      responses:
        200:
          description: User created. Returning stored data
          schema:
            type: array
            items:
              $ref: '#/definitions/PublicUserProfile'
        409:
          description: Client ID already used
          schema:
            $ref: '#/definitions/Conflict'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
    put:
      summary: Modify user
      description: |
        Modifies user public profile if is needed. Only differents paramters are modified. uuid and project are required
      tags:
        - Public Users
      parameters:
        - name: name
          in: body
          description: User data to be modified
          required: true
          schema:
              $ref: '#/definitions/PublicUserProfile'
      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/{uuid}:
    get:
      summary: Retrieve user data
      description: |
        Try to fetch the user with specified uuid and get it back
      tags:
        - Public Users
      parameters:
        - name: uuid
          in: path
          description: User unique identifier
          required: true
          type: string
      responses:
        200:
          description: User fetched
          schema:
            type: array
            items:
              $ref: '#/definitions/PublicUserProfile'
        404:
          description: User with uuid does not exist
          schema:
            $ref: '#/definitions/NotFound'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
    delete:
      summary: Delete user with uuid
      description: |
        Delete the user specified by uuid
      tags:
        - Public Users
      parameters:
        - name: uuid
          in: path
          description: User unique identifier
          required: true
          type: string
      responses:
        200:
          description: User deleted
        404:
          description: User with uuid does not exist
          schema:
            $ref: '#/definitions/NotFound'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  /public/{uuid}/location:
    get:
      summary: Retrieve last user location
      description: |
        User location is sotred frequently, this function return the last known user location
      tags:
        - Public Users
      parameters:
        - name: uuid
          in: path
          description: User unique identifier
          required: true
          type: string
      responses:
        200:
          description: Location
          schema:
            type: array
            items:
              $ref: '#/definitions/PublicUserLocation'
        404:
          description: User with uuid does not exist
          schema:
            $ref: '#/definitions/NotFound'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
    post:
      summary: Add new user location
      description: |
        Add new user locationi
      tags:
        - Public Users
      parameters:
        - name: uuid
          in: path
          description: User unique identifier
          required: true
          type: string
      responses:
        200:
          description: Location
          schema:
            type: array
            items:
              $ref: '#/definitions/PublicUserLocation'
        404:
          description: User with uuid does not exist
          schema:
            $ref: '#/definitions/NotFound'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  /public/find_users:
    get:
      summary: Find users
      description: |
        Find user matching the criteria specified by udata
      tags:
        - Public Users
      parameters:
        - name: udata
          in: body
          description: Criteria to find users
          required: true
          schema:
              $ref: '#/definitions/PublicUserProfile'
      responses:
        200:
          description: Users matching criteria
          schema:
            type: array
            items:
              $ref: '#/definitions/PublicUserProfile'
        404:
          description: No users match criteria
          schema:
            $ref: '#/definitions/NotFound'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  /public/activity:
    post:
      summary: Upload Activity
      description: |
        The user sends an activity to the server. These activities are related to specific modules like QUIZ
      tags:
        - Public Users
      parameters:
        - name: activity
          in: body
          description: JSON data related to the activity.
          required: true
          schema:
            $ref: '#/definitions/Activity'
      tags:
        - Public Users
      responses:
        200:
          description: Activity archived
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  /public/find_activities:
    get:
      summary: Find activities
      description: |
        Find activities matching the criteria specified by adata
      tags:
        - Public Users
      parameters:
        - name: adata
          in: body
          description: Criteria to find activities
          required: true
          schema:
              $ref: '#/definitions/ActivityFilter'
      responses:
        200:
          description: Activities matching criteria
          schema:
            type: array
            items:
              $ref: '#/definitions/Activity'
        404:
          description: No activities match criteria
          schema:
            $ref: '#/definitions/NotFound'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  /public/log:
    post:
      summary: Users action/activities log
      description: |
        This logs is used to track the user activities. Theses are regular activities like play media 
      tags:
        - Public Users
      parameters:
        - name: activity
          in: body
          description: JSON data related to the activity.
          required: true
          schema:
            $ref: '#/definitions/Activity'
      tags:
        - Public Users
      responses:
        200:
          description: Activity archived
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
# define models:
definitions:
  Project:
    type: object
    required:
    - name
    - description
    - servertype
    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).
  Media:
    type: object
    required:
    - project
    - md5sum
    - name
    properties:
      name:
        type: string
        description: File name.
      project:
        type: string
        description: Project owner.
      md5sum:
        type: string
        description: SHA1 based sum to integrity checks purpose.
  PublicUserProfile:
    type: object
    required:
    - uuid
    - type
    - project
    properties:
      uuid:
        type: string
        description: Unique identifier for the user.
      project:
        type: string
        description: Name of the project the app is connected to.
      type:
        type: string
        description: User type (i.e. smartphones)
      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.
  PublicUserLocation:
    type: object
    required:
    - uuid
    - latitude
    - longitude
    properties:
      uuid:
        type: string
        description: Unique identifier for the user.
      latitude:
        type: string
        description: Name of the project the app is connected to.
      longitude:
        type: string
        description: User type (i.e. smartphones)
      timestamp:
        type: string
        description: Seconds since EPOCH
  Activity:
    type: object
    required:
    - type
    - project
    - owner
    - data
    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
      owner:
        type: string
        description: Owner Unique identifier 
      project:
        type: string
        description: Name of the project the app is connected to
  ActivityFilter:
    type: object
    required:
    - filters
    properties:
      offset:
        type: integer
        format: int32
        description: Position in pagination.
      limit:
        type: integer
        format: int32
        description: Number of items to retrieve (default and max 100).
      count:
        type: integer
        format: int32
        description: REVISAR Total number of items available.
      filters:
        $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