openapi: 3.0.0
info:
  version: "1.1"
  title: API for the COVID-19 Tracking QR Code Signin Server.
  description: This is the API for the COVID-19 Contact Tracing QRCode Signin Server
# Added by API Auto Mocking Plugin
servers:
  - description: SwaggerHub API Auto Mocking
    url: https://virtserver.swaggerhub.com/aijaz/QRCodeSigninServer/1.1
security: 
  - TokenHeader: []
tags: 
  - name: Authentication
    description: Authentication-related endpoints
  - name: Attendees signins
    description: Endpoints related to attendees signing in on the premises
  - name: Passwords
    description: Endpoints related to changing and resetting passwords
  - name: Team Members
    description: Endpoints related to team member user accounts
paths:
  /login:
    post:
      security: []
      tags: 
      - Authentication
      summary: "Log in to get an API token"
      description: "Submit your email and password to get an API token"
      requestBody:
        $ref: '#/components/requestBodies/loginPayload'
      responses:
        200: 
          description: Success
          content:
            'application/json': 
              schema:
                $ref: '#/components/schemas/loginResponse'
        401:
          $ref: '#/components/responses/Unauthorized'
          
  /logout:
    post:
      tags:
      - Authentication
      summary: "Log out"
      description: "Log out by deleting your token off the server."
      responses:
        200: 
          description: Success
  /signins:
    get:
      tags:
      - Attendees signins
      summary: "Get signin info"
      description: "Returns a list of signin objects sorted by signin ID descending."
      parameters: 
      - name: "less_than"
        in: "query"
        schema: 
          type: integer
        required: False
        description: "Return signins with IDs less than this value."
      - name: "return_count"
        in: "query"
        schema: 
          type: integer
          default: 100
          minimum: 1
          maximum: 100
        required: False
        description: "Return this many objects"
      responses:
        200:
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/signin'
        401:
          $ref: '#/components/responses/Unauthorized'
        503:
          $ref: '#/components/responses/KeyFailure'
          
  /signin:
    post:
      tags:
      - Attendees signins
      description: "Create a new signin record"
      requestBody:
        $ref: '#/components/requestBodies/signinPayload'
      responses:
        200: 
          description: Success
          content:
            'application/json': 
              schema:
                $ref: '#/components/schemas/signinResponse'
        401:
          $ref: '#/components/responses/Unauthorized'
        503:
          $ref: '#/components/responses/KeyFailure'
          
  /signin/{signinId}:
    get:
      tags:
        - Attendees signins
      summary: Retrieve the information associated with a signin record
      description: >
        Retrieve the information associated with a signin record
      parameters:
        - in: path
          name: signinId
          required: true
          schema: 
            type: integer
            example: 1
          description: The ID of the signin record to be retrieved.
      responses: 
        200: 
          description: Success
          content:
            'application/json': 
              schema:
                $ref: '#/components/schemas/signin'
        401:
          $ref: '#/components/responses/Unauthorized'       
    put:
      tags:
        - Attendees signins
      summary: Update a signin record
      description: >
        Update a signin record
      parameters:
        - in: path
          name: signinId
          required: true
          schema: 
            type: integer
            example: 1
          description: The ID of the signin record to be retrieved.
      requestBody:
        $ref: '#/components/requestBodies/signinPayload'
      responses: 
        200: 
          description: Success
          content:
            'application/json': 
              schema:
                $ref: '#/components/schemas/userRecord'
        401:
          $ref: '#/components/responses/Unauthorized'       
    delete:
      tags:
        - Attendees signins
      summary: Delete a signin record
      description: >
        Delete a signin record      
      parameters:
        - in: path
          name: signinId
          required: true
          schema: 
            type: integer
            example: 1
          description: The ID of the signin record to be deleted.
      responses: 
        200: 
          description: Success
        401:
          $ref: '#/components/responses/Unauthorized'

  /verifyPasswordChange:
    post:
      tags: 
      - Passwords
      summary: "Used for resetting your password when you forgot it"
      description: >
        Another endpoint will generate a password reset code for you. You should 
        use the client app to submit the reset code along with the new password
        to change your password.
      requestBody:
        $ref: '#/components/requestBodies/passwordResetPayload'
      responses: 
        200: 
          description: Success
        401:
          $ref: '#/components/responses/Unauthorized'
      
  /changePassword:
    post:
      tags: 
      - Passwords
      summary: "Used for changing your password"
      description: "Pass in your old password and your new password"
      requestBody:
        $ref: '#/components/requestBodies/changePasswordPayload'
      responses: 
        200: 
          description: Success
        401:
          $ref: '#/components/responses/Unauthorized'
      
  /requestPasswordReset:
    post:
      tags: 
      - Passwords
      summary: "Used for requesting a password reset code"
      description: >
        The admin should run this on behalf of a user who forgot their password. 
        The API will generate a password reset code which the admin should
        then provide to the user. The user can use their client to reset their
        password. Normally the password reset code is mailed to the user,
        but I didn't want to do this in this case because I didn't want to 
        introduce the complicated dependency of having an SMTP server just for
        this purpose. Doing it this way makes it easy for people to adopt this 
        API.
      requestBody:
        $ref: '#/components/requestBodies/requestPasswordResetPayload'
      responses: 
        200: 
          description: Success
          content:
            'application/json': 
              schema:
                $ref: '#/components/schemas/requestPasswordResetResponse'
        401:
          $ref: '#/components/responses/Unauthorized'

  /user:
    post:
      tags:
      - Team Members
      summary: Create a user
      description: Use this endpoint to create a team member (user) record
      requestBody:
        $ref: '#/components/requestBodies/createUserPayload'
      responses: 
        200: 
          description: Success
          content:
            'application/json': 
              schema:
                $ref: '#/components/schemas/createUserResponse'
        401:
          $ref: '#/components/responses/Unauthorized'
  /user/{userId}:
    delete:
      tags:
        - Team Members
      summary: Delete a team member's user record
      description: >
        To preserve referential integrity in the database, the user account 
        will not be deleted from the database. Rather, the password will be
        set to the empty string, effectively preventing that user from logging
        in. Furthermore, all active sessions for that user will be deleted, as will
        any password reset tokens. 
      parameters:
        - in: path
          name: userId
          required: true
          schema: 
            type: integer
            example: 1
          description: The ID of the user record to be deleted.
      responses: 
        200: 
          description: Success
        401:
          $ref: '#/components/responses/Unauthorized'
    get:
      tags:
        - Team Members
      summary: Retrieve the information associated with a team member's user record
      description: >
        Retrieve the information associated with a user's account
      parameters:
        - in: path
          name: userId
          required: true
          schema: 
            type: integer
            example: 1
          description: The ID of the user record to be retrieved.
      responses: 
        200: 
          description: Success
          content:
            'application/json': 
              schema:
                $ref: '#/components/schemas/userRecord'
        401:
          $ref: '#/components/responses/Unauthorized'
  /users:
    get:
      tags:
        - Team Members
      summary: Retrieve the information associated with all team members' user records
      description: >
        Retrieve the information associated with all team members' user records
      responses: 
        200: 
          description: Success
          content:
            'application/json': 
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/userRecord'
        401:
          $ref: '#/components/responses/Unauthorized'



      
components:

  parameters:
    signinId:
      name: id
      in: query
      description: Signin ID
      schema:
        type: integer


  schemas:
          
    'loginResponse': 
      title: "Login Response"
      description: "Payload of successful login"
      type: object
      properties:
        admin: 
          type: boolean
          example: false
          description: "True if this user is an admin. False otherwise"
        login_id: 
          type: integer
          example: 1
          description: "The login id for this user"
        name: 
          type: string
          example: "Firstname Lastname"
          description: "This user's name"
        read_only: 
          type: boolean
          example: false
          description: "True if this user has permissions to write to the database. False otherwise"
        token:
          type: string
          example: 'dc19b0b2-c0e3-821b-821a-d49e8c428479'
          description: "The API key that will be used to authenticate the user."
          
    'signin':
      title: "Signin Object"
      description: "Payload of signin object"
      type: object
      properties:
        id:
          type: integer
          example: 125
          description: The record id
        dt: 
          type: number
          example: 1593409124.23
          description: The original scan time in number of seconds since 1/1/1970 (GMT)
        name:
          type: string
          example: "John Q. Public"
          description: "The person's name"
        phone:
          type: string
          example: "(111)222-3333"
          description: "The person's phone number"
        email:
          type: string
          example: "jqp@example.com"
          description: "The person's email"

      required: ["name", "phone"]
      
    invalidToken: 
      title: "Invalid Token"
      description: "Invalid token"
      type: object
      properties: 
        message:
          type: string
          example: "Login Failed"
          
    keyFailure:
      title: "Key Failure"
      description: "Key Failure"
      type: object
      properties: 
        message:
          type: string
          example: "Key Failures"
          
    signinResponse:
      title: "Signin Response"
      description: "Response when you successfully create a signin record"
      type: object
      properties: 
        result:
          type: integer
          example: 1
          minimum: 1
          maximum: 1
    requestPasswordResetResponse:
      title: "Request Password Reset Response"
      description: "This object contains the password reset code for the user"
      type: object
      properties:
        email:
          type: string
          example: "user@example.com"
          description: "The user's email address"
        guid: 
          type: string
          example: "d5e53b3a-ffc1-4436-b085-04aaed5ec861"
          description: "The password reset code"
    createUserResponse: 
      title: The object that's returned when a user record is created.
      description: The object that's returned when a user record is created.
      type: object
      properties:
        email:
          type: string
          example: "user@example.com"
          description: "The user's email address"
        guid: 
          type: string
          example: "d5e53b3a-ffc1-4436-b085-04aaed5ec861"
          description: "The user's password reset code"
    userRecord:
      title: A team member user record
      description: A team member user record
      type: object
      properties:
        id:
          type: integer
          example: 1
          description: "The id of the user's record"
        name: 
          type: string
          example: John Doe
          description: The user's name
        email:
          type: string
          example: "user@example.com"
          description: "The user's email address"
        admin: 
          type: boolean
          example: true
          description: >
           If the user has admin privileges then the user will be able to create password
           reset requests on behalf of other users, and will also be able to view and edit 
           the data of other users.
        read_only: 
          type: boolean
          example: false
          description: Not used in this version of the API. For future use.

          
  responses: 
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/invalidToken'  
            
    KeyFailure:
      description: Key Failure
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/keyFailure'
            
    SigninResponse:
      description: "The response that's sent when you successfully create a signin"
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/signinResponse'
            
    
  requestBodies:     
    'signinPayload': 
      content: 
        'application/json':
          schema:
            $ref: '#/components/schemas/signin'
    
    'loginPayload': 
      description: "The login payload"
      required: true
      content:
        'application/json':
          schema:
            title: Sample
            type: object
            properties:
              email:
                type: string
                example: "aijaz@example.org"
              password: 
                type: string
                example: "hunter2"
              source: 
                type: string
                enum:
                  - 'iOS'
                  - 'android'
                  - 'web'
    passwordResetPayload:
      description: "Password Reset Payload"
      required: true
      content:
        'application/json': 
          schema: 
            title: Sample
            type: object
            properties:
              guid: 
                type: string
                example: "d5e53b3a-ffc1-4436-b085-04aaed5ec861"
                description: "The password reset code"
              password: 
                type: string
                example: "hunter3"
                description: "The new password"
    changePasswordPayload:
      description: "Change Password Payload"
      required: true
      content:
        'application/json': 
          schema: 
            title: Sample
            type: object
            properties:
              old_password: 
                type: string
                example: "hunter3"
                description: "The old (current) password"
              password: 
                type: string
                example: "hunter4"
                description: "The new password"
    requestPasswordResetPayload:
      description: "Request Password Reset Payload"
      required: true
      content:
        'application/json': 
          schema: 
            title: Sample
            type: object
            properties:
              email: 
                type: string
                example: "user@example.com"
                description: "The user whose password you want to reset"
    createUserPayload:
      description: "Create User Payload"
      required: true
      content:
        'application/json': 
          schema: 
            title: Sample
            type: object
            properties:
              email: 
                type: string
                example: "user@example.com"
                description: "The email address of the user record you want to create"
              name: 
                type: string
                example: "Jane Doe"
                description: "The name of the user record you want to create"
              admin: 
                type: boolean
                example: true
                description: >
                 If the user has admin privileges then the user will be able to create password
                 reset requests on behalf of other users, and will also be able to view and edit 
                 the data of other users.
              read_only: 
                type: boolean
                example: false
                description: Not used in this version of the API. For future use.


  securitySchemes:
    TokenHeader:
      type: apiKey
      description: Token to authorize requests.
      name: token
      in: header