swagger.yaml

swagger: '2.0'
info:
  version: '1.0'
  title: "ArenaKeys"
  description: |
    ArenaKeys is a service that allows users to look for their favourite games at the lowest price! 
    
    It offers you the means to authenticate them through Steam OpenID or Google OAuth2 hiding the complexity of the process and 
    allowing to save the data to create an account that might be useful for future usages.
    In fact, each account can have multiple lists of games related to it, where, for each game, you'll able to easily find out a few hot
    deals on official and/or unofficial third-party resellers like:
      * [Steam](https://store.steampowered.com/)
      * [Gamivo](https://www.gamivo.com/)
      * [CDKeys](https://adm.cdkeys.com/)
      * [HRKGame](https://www.hrkgame.com/)
      
  license:
    name: MIT
    url: https://github.com/apiaryio/polls-api/blob/master/LICENSE

host: ec2-34-245-97-253.eu-west-1.compute.amazonaws.com

basePath: /

schemes:
- https

consumes:
- application/json

produces:
- application/json
- text/plain

securityDefinitions:
  Google access token:
    type: oauth2
    flow: accessCode
    authorizationUrl: http://ec2-34-245-97-253.eu-west-1.compute.amazonaws.com/auth/google
    tokenUrl: http://ec2-34-245-97-253.eu-west-1.compute.amazonaws.com/auth/google/callback
    scopes:
      list: Grants read/write on lists of his/her own
      user: Grants read/write on his/her profile data
      
  Steam access token:
    type: oauth2
    flow: accessCode
    authorizationUrl: http://ec2-34-245-97-253.eu-west-1.compute.amazonaws.com/auth/steam
    tokenUrl: http://ec2-34-245-97-253.eu-west-1.compute.amazonaws.com/auth/steam/return
    scopes:
      list: Grants read/write on lists of his/her own
      user: Grants read/write on his/her profile data
tags:
  - name: Authentication
  - name: User Management
  - name: User List Management
  - name: Videogame
  
paths:
  
  '/auth/google':
    get:
      tags:
        - Authentication
      operationId: authGoogle
      summary: Authentication with Google
      description: |
        This call manages the authentication process of a user through the usage of a Google account. The response gives back a token to identify the user and check if he/she is correctly authenticated through the session defined by the same token.
        
        The token is going to be valid for two hours since the moment it has been generated.
      responses:
        200:
          description: Successful
          schema:
            type: object
            properties:
              user:
                type: object
                $ref: '#/definitions/googleUserAuth'
              token:
                type: string
  
  '/auth/steam':
    get:
      tags:
        - Authentication
      operationId: authSteam
      summary: Authentication with Steam
      description: |
        This call manages the authentication process of a user through the usage of a Steam account. The response gives back a token to identify the user and check if he/she is correctly authenticated through the session defined by the same token.
        
        The token is going to be valid for two hours since the moment it has been generated.
      responses:
        200:
          description: Success
          schema:
            type: object
            properties:
              user:
                type: object
                $ref: '#/definitions/steamUserAuth'
              token:
                type: string
                
  '/steam/user':
    get:
      summary: Get User 
      description: |
        This call gets the user's data once already signed up into the system through a Steam account.
        
        **Note**: You're not going to be able to access other user's data because your id is directly extracted from a valid and freshly generated token 
      tags:
        - User Management
      security:
        - Bearer: [<token>]
      parameters:
        - in: header
          name: Authorization
          type: string
          required: true
          description: The authorization token is used to identify the user and check to which data he/she has access to.
      responses:
        '200':
          description: Success
          schema:
            type: object
            $ref: '#/definitions/userObj'
                
        '400':
          description: Bad Request
          schema:
            type: object
            properties:
              responseStatus:
                $ref: '#/definitions/ResponseStatus'
    post:
      summary: Register new User
      description: |
        This call creates the user if it doesn't exist (using the basic sample of data retrieved from the initial auth [/auth/steam](#/Authentication/authSteam)).
      
        **Note**: you still need a valid token to perform the POST operation and create the user, therefore it's allowed to create a user which corresponds to the steam account's data retrievable from the token (same steamUserId)
      tags:
        - User Management
      security:
        - Bearer: [<token>]
      parameters:
      - name: Authorization
        in: header
        type: string
        required: true
        description: The authorization token is used to identify the user and check to which data he/she has access to. 
      - name: user
        in: body
        required: true
        schema:
          $ref: '#/definitions/userObj'
        description: the user object contains all the user information that will be used to create the user for the first time.
      responses:
        201:
          description: Success
          schema:
            type: object
            $ref: '#/definitions/userObj'
        400:
          description: Bad Request
          schema:
            type: object
            properties:
              responseStatus:
                $ref: '#/definitions/ResponseStatus'
    put:
      summary: Edit User
      description: |
        This call is used to edit the user's personal information. 
        
        **Note**: edit just the values you're supposed to and not ids, in any case the PUT operation is not going to modify them.
      tags:
        - User Management
      security:
        - Bearer: [<token>]
      parameters:
      - name: Authorization
        in: header
        type: string
        required: true
        description: The authorization token is used to identify the user and check to which data he/she has access to. 
      - name: user
        in: body
        required: true
        schema:
          $ref: '#/definitions/userObj'
        description: the user object contains all the user information that can be modified.
      responses:
        200:
          description: Success
          schema:
            type: object
            $ref: '#/definitions/userObj'
        400:
          description: Bad Request
          schema:
            type: object
            properties:
              responseStatus:
                $ref: '#/definitions/ResponseStatus'
        404:
          description: Not Found
          schema:
            type: object
            properties:
              responseStatus:
                $ref: '#/definitions/ResponseStatus'
    delete:
      summary: Delete User
      description: This call is used to delete a user and all the related information such as personal data and lists.
      tags:
        - User Management
      security:
        - Bearer: [<token>]
      parameters:
      - name: Authorization
        in: header
        type: string
        required: false
        description: The authorization token is used to identify the user and check to which data he/she has access to.
      - name: user
        in: body
        required: true
        schema:
          $ref: '#/definitions/userObj'
        description: the user object contains all the user information that to be deleted.
      responses:
        200:
          description: Success
          schema:
            type: object
            $ref: '#/definitions/userObj'
        404:
          description: Not Found
          schema:
            type: object
            properties:
              responseStatus:
                $ref: '#/definitions/ResponseStatus'
  
  '/google/user':
    get:
      summary: Get User 
      description: |
        This call gets the user's data once already signed up into the system through a Google account.
        
        **Note**: You're not going to be able to access other user's data because your id is directly extracted from a valid and freshly generated token 
      tags:
        - User Management
      security:
        - Bearer: [<token>]
      parameters:
        - in: header
          name: Authorization
          type: string
          required: true
          description: The authorization token is used to identify the user and check to which data he/she has access to.
      responses:
        '200':
          description: Success
          schema:
            type: object
            $ref: '#/definitions/userObj'
        '400':
          description: Bad Request
          schema:
            type: object
            properties:
              responseStatus:
                $ref: '#/definitions/ResponseStatus'
    post:
      summary: Register new User
      description: |
        This call creates the user if it doesn't exist (using the basic sample of data retrieved from the initial auth [/auth/google](#/Authentication/authGoogle)).
      
        **Note**: you still need a valid token to perform the POST operation and create the user, therefore it's allowed to create a user which corresponds to the google account's data retrievable from the token (same googleUserId)
      tags:
        - User Management
      security:
        - Bearer: [<token>]
      parameters:
      - name: Authorization
        in: header
        type: string
        required: true
        description: The authorization token is used to identify the user and check to which data he/she has access to.
      - name: user
        in: body
        required: true
        schema:
          $ref: '#/definitions/userObj'
        description: the user object contains all the user information that will be used to create the user for the first time.
      responses:
        201:
          description: Success
          schema:
            type: object
            $ref: '#/definitions/userObj'
        400:
          description: Bad Request
          schema:
            type: object
            properties:
              responseStatus:
                $ref: '#/definitions/ResponseStatus'
    put:
      summary: Edit User
      description: |
        This call is used to edit the user's personal information. 
        
        **Note**: edit just the values you're supposed to and not ids, in any case the PUT operation is not going to modify them. 
      tags:
        - User Management
      security:
        - Bearer: [<token>]
      parameters:
      - name: Authorization
        in: header
        type: string
        required: true
        description: The authorization token is used to identify the user and check to which data he/she has access to.
      - name: user
        in: body
        required: true
        schema:
          $ref: '#/definitions/userObj'
        description: the user object contains all the user information that can be modified.
      responses:
        200:
          description: Success
          schema:
            type: object
            $ref: '#/definitions/userObj'
        400:
          description: Bad Request
          schema:
            type: object
            properties:
              responseStatus:
                $ref: '#/definitions/ResponseStatus'
        404:
          description: Not Found
          schema:
            type: object
            properties:
              responseStatus:
                $ref: '#/definitions/ResponseStatus'
    delete:
      summary: Delete User
      description: This call is used to delete a user and all the related information such as personal data and lists.
      tags:
        - User Management
      security:
        - Bearer: [<token>]
      parameters:
      - name: Authorization
        in: header
        type: string
        required: true
        description: The authorization token is used to identify the user and check to which data he/she has access to.
      - name: user
        in: body
        required: true
        schema:
          $ref: '#/definitions/userObj'
        description: the user object contains all the user information that to be deleted.
      responses:
        200:
          description: Success
          schema:
            type: object
            $ref: '#/definitions/userObj'
        404:
          description: Not Found
          schema:
            type: object
            properties:
              responseStatus:
                $ref: '#/definitions/ResponseStatus'

  '/steamwishlist/{steamUserID}':
    get:
      summary: Get steam wishlist
      description: This call the steam wishlist of the selected user (given its steam user id and the fact that its profile is public) with respect to the standard and the additional informations provided by ArenaKeys.
      tags:
        - User List Management
      parameters:
      - in: path
        name: steamUserID
        type: string
        required: true
        description: The steam id of the user of which we are interested to fetch the wishlist
      - name: details
        in: query
        type: boolean
        required: false
        default: true
        description: shows or hides useful information about a game such as the image, the description and the last update
      - name: offers
        in: query
        type: boolean
        required: false
        default: true
        description: shows or hides data related to the game's available offers 
      responses:
        200:
          description: Success
          schema:
            type: object
            $ref: '#/definitions/list'
            description: contains the requested steam wishlist formatted following the standards of ArenaKeys.     
                
        400:
          description: Bad Request
          schema:
            type: object
            properties:
              responseStatus:
                $ref: '#/definitions/ResponseStatus'

        404:
          description: Bad Request
          schema:
            type: object
            properties:
              responseStatus:
                $ref: '#/definitions/ResponseStatus'      

  '/steam/userlist':
    get:
      summary: Get all user's Lists
      description: This call returns all the lists that have been created by the steam-logged user.
      tags:
        - User List Management
      security:
        - Bearer: [<token>]
      parameters:
      - in: header
        name: Authorization
        type: string
        required: true
        description: The authorization token is used to identify the user and check to which data he/she has access to.
      - name: details
        in: query
        type: boolean
        required: false
        default: true
        description: shows or hides useful information about a game such as the image, the description and the last update
      - name: offers
        in: query
        type: boolean
        required: false
        default: true
        description: shows or hides data related to the game's available offers
      responses:
        200:
          description: Success
          schema:
            type: array
            items:
              $ref: '#/definitions/list'
              description: this array contains all the lists of a user.
                
        400:
          description: Bad Request
          schema:
            type: object
            properties:
              responseStatus:
                $ref: '#/definitions/ResponseStatus'
    post:
      summary: Create a list
      description: This call creates and returns a list of games chosen by the logged user.
      tags:
        - User List Management
      security:
        - Bearer: [<token>]
      parameters:
      - name: Authorization
        in: header
        type: string
        required: true
        description: The authorization token is used to identify the user and check to which data he/she has access to.
      - name: list
        in: body
        required: true
        schema:
          $ref: '#/definitions/listNoId'
        description: the list has all the games that the logged user has inserted
      responses:
        201:
          description: Success
          schema:
            type: object
            $ref: '#/definitions/list'
            description: this object contains the list name and all the games in it.
                              
        400:
          description: Bad Request
          schema:
            type: object
            properties:
              responseStatus:
                $ref: '#/definitions/ResponseStatus'
  
  '/steam/userlist/{id}':
    get:
      summary: Get a List
      description: This call returns the list of a steam-logged user given its id.
      tags:
        - User List Management
      security:
        - Bearer: [<token>]
      parameters:
      - in: header
        name: Authorization
        type: string
        required: true
        description: The authorization token is used to identify the user and check to which data he/she has access to.
      - in: path
        name: id
        type: integer
        required: true
        description: the id of the requested list
      - name: details
        in: query
        type: boolean
        required: false
        default: true
        description: shows or hides useful information about a game such as the image, the description and the last update
      - name: offers
        in: query
        type: boolean
        required: false
        default: true
        description: shows or hides data related to the game's available offers
      responses:
        200:
          description: Success
          schema:
            type: object
            $ref: '#/definitions/list'
            description: this object contains the list name and all the games in it.
        400:
          description: Bad Request
          schema:
            type: object
            properties:
              responseStatus:
                $ref: '#/definitions/ResponseStatus'
    put:
      summary: Edit a List 
      description: |
        This call modifies and returns list of a steam-logged user given its id.

        **Note** that even if a whole list object is required, the necessary elements (needed to identify the list and strictly related to the logged user) and the ones which can be modified (such
        as the items providing at least theirs steamID and eventually the notification price, but it does not make any sense to provide and/or alterate the offers for them, because they'll be dynamically computed
        by our engine)
      tags:
        - User List Management
      security:
        - Bearer: [<token>]
      parameters:
      - name: Authorization
        in: header
        type: string
        required: true
        description: The authorization token is used to identify the user and check to which data he/she has access to.
      - name: list
        in: body
        required: true
        schema:
          $ref: '#/definitions/list'
        description: this object contains the list name and all the games in it.
      - in: path
        name: id
        type: integer
        required: true
        description: the id of the list
      responses:
        200:
          description: Success
          schema:
            type: object
            $ref: '#/definitions/list'
            description: this object contains the list name and all the games in it.
        400:
          description: Bad Request
          schema:
            type: object
            properties:
              responseStatus:
                $ref: '#/definitions/ResponseStatus'
        404:
          description: Not Found
          schema:
            type: object
            properties:
              responseStatus:
                $ref: '#/definitions/ResponseStatus'
    delete:
      summary: Delete a List
      description: This call deletes and returns the list of a steam-logged user given its id.
      tags:
        - User List Management
      security:
        - Bearer: [<token>]
      parameters:
      - name: Authorization
        in: header
        type: string
        required: true
        description: The authorization token is used to identify the user and check to which data he/she has access to.
      - name: list
        in: body
        required: true
        schema:
          $ref: '#/definitions/list'
        description: this object contains the list name and all the games in it.
      - in: path
        name: id
        type: integer
        required: true
        description: the id of the list
      responses:
        200:
          description: Success
          schema:
            type: object
            $ref: '#/definitions/list'
            description: this object contains the list name and all the games in it.
        404:
          description: Not Found
          schema:
            type: object
            properties:
              responseStatus:
                $ref: '#/definitions/ResponseStatus'
  
  '/google/userlist':
    get:
      summary: Get all user's Lists
      description: This call returns all the lists that have been created by the google-logged user.
      tags:
        - User List Management
      security:
        - Bearer: [<token>]
      parameters:
      - in: header
        name: Authorization
        type: string
        required: true
        description: The authorization token is used to identify the user and check to which data he/she has access to.
      - name: details
        in: query
        type: boolean
        required: false
        default: true
        description: shows or hides useful information about a game such as the image, the description and the last update
      - name: offers
        in: query
        type: boolean
        required: false
        default: true
        description: shows or hides data related to the game's available offers
      responses:
        200:
          description: Success
          schema:
            type: array
            items:
              $ref: '#/definitions/list'
              description: this array contains all the lists of a user.
        400:
          description: Bad Request
          schema:
            type: object
            properties:
              responseStatus:
                $ref: '#/definitions/ResponseStatus'
    post:
      summary: Create a list
      description: This call creates and returns a list of games chosen by the logged user. 
      tags:
        - User List Management
      security:
        - Bearer: [<token>]
      parameters:
      - name: Authorization
        in: header
        type: string
        required: true
        description: The authorization token is used to identify the user and check to which data he/she has access to.
      - name: list
        in: body
        required: true
        schema:
          $ref: '#/definitions/listNoId'
        description: the list has all the games that the logged user has inserted
      responses:
        201:
          description: Success
          schema:
            type: object
            $ref: '#/definitions/list'
            description: this object contains the list name and all the games in it.
        400:
          description: Bad Request
          schema:
            type: object
            properties:
              responseStatus:
                $ref: '#/definitions/ResponseStatus'
  
  '/google/userlist/{id}':
    get:
      summary: Get a List
      description: This call returns the list of a google-logged user given its id.
      tags:
        - User List Management
      security:
        - Bearer: [<token>]
      parameters:
      - in: header
        name: Authorization
        type: string
        required: true
        description: The authorization token is used to identify the user and check to which data he/she has access to.
      - in: path
        name: id
        type: integer
        required: true
        description: the id of the list
      - name: details
        in: query
        type: boolean
        required: false
        default: true
        description: shows or hides useful information about a game such as the image, the description and the last update
      - name: offers
        in: query
        type: boolean
        required: false
        default: true
        description: shows or hides data related to the game's available offers 
      responses:
        200:
          description: Success
          schema:
            type: object
            $ref: '#/definitions/list'
            description: this object contains the list name and all the games in it.
        400:
          description: Bad Request
          schema:
            type: object
            properties:
              responseStatus:
                $ref: '#/definitions/ResponseStatus'
    put:
      summary: Edit a List
      description: |
        This call modifies and returns the list of a google-logged user given its id.
        
        **Note** that even if a whole list object is required, the necessary elements (needed to identify the list and strictly related to the logged user) and the ones which can be modified (such
        as the items providing at least theirs steamID and eventually the notification price, but it does not make any sense to provide and/or alterate the offers for them, because they'll be dynamically computed
        by our engine)
      tags:
        - User List Management
      security:
        - Bearer: [<token>]
      parameters:
      - name: Authorization
        in: header
        type: string
        required: true
        description: The authorization token is used to identify the user and check to which data he/she has access to.
      - name: list
        in: body
        required: true
        schema:
          $ref: '#/definitions/list'
        description: this object contains the list name and all the games in it.
      - in: path
        name: id
        type: integer
        required: true
        description: the id of the list
      responses:
        200:
          description: Success
          schema:
            type: object
            $ref: '#/definitions/list'
            description: this object contains the list name and all the games in it.
        400:
          description: Bad Request
          schema:
            type: object
            properties:
              responseStatus:
                $ref: '#/definitions/ResponseStatus'
        404:
          description: Not Found
          schema:
            type: object
            properties:
              responseStatus:
                $ref: '#/definitions/ResponseStatus'
    delete:
      summary: Delete a List
      description: This call deletes and returns the list of a google-logged user given its id.
      tags:
        - User List Management
      security:
        - Bearer: [<token>]
      parameters:
      - name: Authorization
        in: header
        type: string
        required: true
        description: The authorization token is used to identify the user and check to which data he/she has access to.
      - name: list
        in: body
        required: true
        schema:
          $ref: '#/definitions/list'
        description: this object contains the list name and all the games in it.
      - in: path
        name: id
        type: integer
        required: true
        description: the id of the list
      responses:
        200:
          description: Success
          schema:
            type: object
            $ref: '#/definitions/list'
            description: this object contains the list name and all the games in it.
        404:
          description: Not Found
          schema:
            type: object
            properties:
              responseStatus:
                $ref: '#/definitions/ResponseStatus'
  
  '/videogame':
    get:
      summary: Search for matching games
      description: This call allows to look for one or more games given the name, finding their data (title, image, description) and the available offers for them (with the last date in which those ones had been checked)
      tags:
        - Videogame
      parameters:
      - name: name
        in: query
        type: string
        minLength: 2
        required: true
        description: the name of the game
      - name: details
        in: query
        type: boolean
        required: false
        default: true
        description: shows or hides useful information about a game such as the image, the description and the last update
      - name: offers
        in: query
        type: boolean
        required: false
        default: true
        description: shows or hides data related to the game's available offers 
      responses:
        200:
          description: Success
          schema:
            type: object
            properties:
              game:
                type: array
                items:
                  $ref: '#/definitions/gameOffer'
                description: this array contains all the games found given the steamID or the name
  
  '/videogame/{steamID}':
    get:
      summary: Search for a game
      description: This call allows to look for a specific game given its steamID, finding its data (title, image, description) and the available offers for it (with the last date in which those ones had been checked)
      tags:
        - Videogame
      parameters:
      - name: steamID
        in: path
        type: integer
        required: true
        description: the game identifier
      - name: details
        in: query
        type: boolean
        required: false
        default: true
        description: shows or hides useful information about a game such as the image, the description and the last update
      - name: offers
        in: query
        type: boolean
        required: false
        default: true
        description: shows or hides data related to the game offers 
      responses:
        200:
          description: Success
          schema:
            type: object
            $ref: '#/definitions/gameOffer'
        404:
          description: Not Found
          schema:
            type: object
            properties:
              responseStatus:
                $ref: '#/definitions/ResponseStatus'

definitions:

  steamUserAuth:
    title: Steam User
    type: object
    properties:
      steamUserId:
        type: integer
      name:
        type: string
      imageLink:
        type: string
      steamProfileUrl:
        type: string

  googleUserAuth:
    title: Google User
    type: object
    properties:
      googleUserId:
        type: integer
      name:
        type: string
      email:
        type: string
      imageLink:
        type: string

  userObj:
    title: User Object
    type: object
    properties:
      steamUserId:
        type: string
      googleUserId:
        type: string
      name:
        type: string
      imageLink:
        type: string
      email:
        type: string
      id:
        type: integer
      steamProfileUrl:
        type: string
    required:
      - name
      - imageLink
      - id
  
  list:
    title: list
    type: object
    properties:
      id:
        type: integer
      userId:
        type: string
      name:
        type: string
      notifyMe:
        type: boolean
        default: true
      items: 
        type: array
        items:
          $ref: '#/definitions/listItem'
    required:
      - id
      - name
      - notifyMe
      - items
  
  listNoId:
    title: List with no id
    type: object
    properties:
      userId:
        type: string
      name:
        type: string
      notifyMe:
        type: boolean
      items: 
        type: array
        items:
          $ref: '#/definitions/listItem'
    required:
      - name
      - notifyMe
      - items
  
  listItem:
    title: listItem
    type: object
    properties:
      steamID:
        type: integer
      name:
        type: string
      priceNotifier:
        type: boolean
      notified:
        type: boolean
      imageLink:
        type: string
      description:
        type: string
      offers:
        type: array
        items:
          $ref: '#/definitions/offerItem'
    required:
      - name
      - priceNotifier
      - imageLink
      - offers
  
  gameOffer:
    title: Game Offer
    type: object
    properties:
      steamID:
        type: integer
      name:
        type: string
      imageLink:
        type: string
      description:
        type: string
      lastUpdate:
        type: string
      offers:
        type: array
        items:
          $ref: '#/definitions/offerItem'
    required:
      - steamID
      - name
      - imageLink
      - offers
  
  offerItem:
    title: Offer Item
    type: object
    properties:
      reseller:
        type: string
      price:
        type: number
      link:
        type: string
      availability:
        type: boolean
    required:
      - reseller
      - price
      - link
      - availability
  
  ResponseStatus:
    type: object
    description: Response status code, with a better explanation of what could be the possible causes of the error
    properties:
      status:
        type: number
        default: 200
      code:
        type: string
        default: OK
      msg:
        type: string
        description: Additional string attached to the status in order to understand better the nature of the errorss