HogWeedGo.openapi.yml

openapi: 3.0.3

info:
  title: HogWeedGo service openapi specification
  version: 0.0.1



paths:
  /healthcheck:
    get:
      operationId: healthcheck
      description: "Endpoint to check whether the HogWeed server is alive."
      responses:
        '200':
          content:
            text/plain:
              schema:
                pattern: '^healthy$'
          description: "Server is up and healthy."
      tags:
        - health
        - unauth

  /api/me/prove_email:
    get:
      operationId: proveEmail
      description: "Endpoint to generate a unique code for given email. It is required for authentication and stays valid for 10 minutes."
      parameters:
        - in: query
          name: email
          schema:
            type: string
            format: email
          required: true
          description: "Email the code is requested for."
      responses:
        '200':
          content:
            text/plain:
              schema:
                pattern: '^Code was sent$'
                description: "Response of server in production environment."
            application/json:
              schema:
                $ref: '#/components/schemas/Email'
          description: "The code was successfully generated and sent. If environment variable MOCK_SMTP_SERVER is set to True response will be sent as JSON. Otherwise it will be sent to specified email."
      tags:
        - me
        - unauth

  /api/me/auth:
    get:
      operationId: auth
      description: "Endpoint for creating new user (with given email)."
      parameters:
        - in: query
          name: email
          schema:
            type: string
            format: email
          required: true
          description: "Email user account is created with."
        - in: query
          name: code
          schema:
            type: string
          required: true
          description: "Special unique registration code (usually received by email from '/api/me/prove_email' endpoint)."
        - in: query
          name: password
          schema:
            type: string
          required: true
          description: "Password of newly created user."
      responses:
        '200':
          content:
            application/json:
              schema:
                pattern: '^Token (?<TOKEN>[a-z0-9]*)$'
          description: "New user is successfully created. TOKEN stands for user session auth token. To log in user should add Authentication: Token TOKEN' header to his request."
        '401':
          content:
            text/plain:
              schema:
                pattern: '^Wrong or expired code!$'
          description: "Provided code was wrong or expired (sent more than 10 minutes after being requested)."
        '403':
          content:
            text/plain:
              schema:
                pattern: '^User already exists!$'
          description: "User with provided email already exists."
        '400':
          content:
            text/plain:
              schema:
                pattern: '^Can not (?:authenticate|log in) user with email: (?<EMAIL>\S*), password: (?<PASSWORD>\S*)!$'
          description: "User can not be created for unknown reason. EMAIL and PASSWORD stand for email and password provided in params."
        '429':
          content:
            application/json:
              schema:
                description: '^Request was throttled\. Expected available in (?<SECONDS>[0-9]*) seconds?\.$'
          description: "This endpoint may be called maximum 4 times per minute."
      tags:
        - me
        - unauth

  /api/me/log_in:
    get:
      operationId: logIn
      description: "Endpoint for logging existing user in."
      parameters:
        - in: query
          name: email
          schema:
            type: string
            format: email
          required: true
          description: "Email user account is created with."
        - in: query
          name: password
          schema:
            type: string
          required: true
          description: "Password of newly created user."
      responses:
        '200':
          content:
            application/json:
              schema:
                pattern: '^Token (?<TOKEN>[a-z0-9]*)$'
          description: "User is successfully logged in. TOKEN stands for user session auth token. To log in user should add 'Authentication: Token [TOKEN]' header to his request."
        '400':
          content:
            text/plain:
              schema:
                pattern: '^Can not (?:authenticate|log in) user with email: (?<EMAIL>\S*), password: (?<PASSWORD>\S*)!$'
          description: "User can not be logged in. EMAIL and PASSWORD stand for email and password provided in params."
        '429':
          content:
            application/json:
              schema:
                description: '^Request was throttled\. Expected available in (?<SECONDS>[0-9]*) seconds?\.$'
          description: "This endpoint may be called maximum 4 times per minute."
      tags:
        - me
        - unauth

  /api/me/profile:
    get:
      operationId: profile
      description: "Endpoint for retrieving information about current user."
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
          description: "Current user profile."
      security:
        - HogWeedAuth: []
      tags:
        - me
        - auth

  /api/me/setup:
    post:
      operationId: setupMe
      description: "Endpoint for altering user information (such as email, password, name or profile picture)."
      parameters:
        - in: query
          name: email
          schema:
            type: string
            format: email
          description: "New email for current user."
        - in: query
          name: code
          schema:
            type: string
          description: "Special unique registration code (usually received by email from '/api/me/prove_email' endpoint). Required for email changing only."
        - in: query
          name: password
          schema:
            type: string
          description: "New password for current user."
        - in: query
          name: name
          schema:
            type: string
          description: "New name of current user."
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                photo:
                  type: string
                  format: binary
              additionalProperties: false
        description: "New profile picture of current user."
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Setup'
          description: "All requested user properties were successfully changed."
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Setup'
          description: "At least one of the requested properties could not be changed."
        '429':
          content:
            application/json:
              schema:
                description: '^Request was throttled\. Expected available in (?<SECONDS>[0-9]*) seconds?\.$'
          description: "This endpoint may be called maximum 4 times per minute."
      security:
        - HogWeedAuth: []
      tags:
        - me
        - auth

  /api/me/log_out:
    delete:
      operationId: logOut
      description: "Endpoint for logging current user out (finishing his session and deleting token)."
      responses:
        '200':
          content:
            text/plain:
              schema:
                pattern: '^Logged out successfully$'
          description: "User was logged out successfully, his token is valid no more."
      security:
        - HogWeedAuth: []
      tags:
        - me
        - auth

  /api/me/leave:
    delete:
      operationId: leave
      description: "Endpoint for deleting current user."
      responses:
        '200':
          content:
            text/plain:
              schema:
                pattern: '^User deleted successfully$'
          description: "User was deleted successfully, all his information removed from server."
      security:
        - HogWeedAuth: []
      tags:
        - me
        - auth

  /api/reports:
    get:
      operationId: listReports
      description: "Endpoint for getting all reports ever sent."
      parameters:
        - in: query
          name: filter
          schema:
            enum:
              - RECEIVED
              - APPROVED
              - INVALID
            type: string
          description: "Optional filter for requested reports (returns all if not set)."
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: integer
                  next:
                    type: string
                    format: uri
                    nullable: true
                  previous:
                    type: string
                    format: uri
                    nullable: true
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/ReportOut'
                additionalProperties: false
                required:
                  - count
                  - next
                  - previous
                  - results
          description: "Reports list."
      tags:
        - api
    post:
      operationId: createReport
      description: "Endpoint for creating a new report."
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                data:
                  $ref: '#/components/schemas/ReportIn'
                photos:
                  type: array
                  items:
                    type: string
                    format: binary
              additionalProperties: false
              required:
                - data
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportOut'
          description: "New added report."
        '400':
          content:
            application/json:
              schema:
                type: string
          description: "Report can not be created because of data integrity validation failure."
        '429':
          content:
            application/json:
              schema:
                description: '^Request was throttled\. Expected available in (?<SECONDS>[0-9]*) seconds?\.$'
          description: "This endpoint may be called maximum 4 times per minute."
      security:
        - HogWeedAuth: []
      tags:
        - auth

  /api/users/{id}:
    get:
      operationId: retrieveUser
      description: "Endpoint for retrieving information about particular service user."
      parameters:
        - in: path
          name: id
          schema:
            type: integer
          required: true
          description: "A unique integer value identifying this User."
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
          description: "User profile."
      tags:
        - api
        - user

  /api/comments:
    post:
      operationId: createComment
      description: "Endpoint for creating a new comment."
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CommentIn'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommentOut'
          description: "Comment was successfully created."
        '400':
          content:
            application/json:
              schema:
                type: string
          description: "Report can not be created because of data integrity validation failure."
        '429':
          content:
            application/json:
              schema:
                description: '^Request was throttled\. Expected available in (?<SECONDS>[0-9]*) seconds?\.$'
          description: "This endpoint may be called maximum 4 times per minute."
      security:
        - HogWeedAuth: []
      tags:
        - comment
        - auth



components:
  schemas:
    Email:
      type: object
      properties:
        subject:
          pattern: '^HogWeedGo authentication$'
        message:
          pattern: '^Your confirmation code is: "(?<TOKEN>[0-9]*)"\nIt will be valid for 10 minutes\.$'
          description: "TOKEN stands for a token, unique for given server and email, valid for 10 minutes."
        recipients:
          type: array
          items:
            type: string
            format: email
          minItems: 1
          maxItems: 1
          description: "Email the code is generated for."
      additionalProperties: false
      required:
        - subject
        - message
        - recipients

    Setup:
      type: object
      properties:
        email:
          enum:
            - Wrong or expired code!
            - Saved!
            - User with given email already exists!
            - Code required!
          type: string
          description: "Describes whether user email was altered and if not why."
        token:
          pattern: '^Email required!$'
          description: "Describes that confirmation code was sent without email."
        password:
          pattern: '^Saved!$'
          description: "Describes whether user password was changed."
        name:
          pattern: '^Saved!$'
          description: "Describes whether user name was changed."
        photo:
          pattern: '^Saved!$'
          description: "Describes whether user profile picture was changed."
      additionalProperties: false
      
    Location:
      type: object
      properties:
        lng:
          type: number
        lat:
          type: number
      additionalProperties: false
      required:
        - lng
        - lat

    ReportIn:
      type: object
      properties:
        address:
          type: string
          nullable: true
          description: "Address defined by user. May be just a geo-related recommendation."
          maxLength: 128
        init_comment:
          type: string
          description: "User comment about the report."
          maxLength: 2048
        place:
          $ref: '#/components/schemas/Location'
        type:
          type: string
          description: "User guess for report."
          maxLength: 64
      additionalProperties: false
      required:
        - init_comment
        - place
        - type

    ReportOut:
      type: object
      properties:
        address:
          type: string
          nullable: true
          description: "Address defined by user. May be just a geo-related recommendation."
          maxLength: 128
        init_comment:
          type: string
          description: "User comment about the report."
          maxLength: 2048
        date:
          type: string
          format: number
          description: "Date specified by user for his observation."
        status:
          enum:
            - RECEIVED
            - APPROVED
            - INVALID
          type: string
          description: "Report status."
        subs:
          type: integer
          nullable: true
          description: "The sender of the report, subscription."
        id:
          type: integer
          description: "Unique identifier of this report."
        type:
          type: string
          description: "Staff reply for the report."
          maxLength: 64
        place:
          $ref: '#/components/schemas/Location'
        photos:
          type: array
          items:
            type: object
            properties:
              photo:
                type: string
                format: uri
              thumbnail:
                type: string
                format: uri
            additionalProperties: false
            required:
              - photo
              - thumbnail
        comments:
          type: array
          items:
            $ref: "#/components/schemas/CommentOut"
      additionalProperties: false
      required:
        - init_comment
        - date
        - status
        - subs
        - id
        - type
        - place
        - photos
        - comments

    User:
      type: object
      properties:
        last_login:
          type: string
          format: date-time
          nullable: true
        first_name:
          type: string
          maxLength: 150
          nullable: true
        is_staff:
          type: boolean
          description: "Designates whether the user can log into this admin site."
        photo:
          type: string
          format: uri
          nullable: true
        thumbnail:
          type: string
          format: uri
          nullable: true
      additionalProperties: false
      required:
        - is_staff

    CommentIn:
      type: object
      properties:
        report:
          type: integer
          description: "Report this comment is attached to."
        text:
          type: string
          description: "A comment, added to a report by another user."
          maxLength: 2048
      additionalProperties: false
      required:
        - report
        - text

    CommentOut:
      type: object
      properties:
        report:
          type: integer
          description: "Report this comment is attached to."
        text:
          type: string
          description: "A comment, added to a report by another user."
          maxLength: 2048
        subs:
          type: integer
          nullable: true
          description: "Author of the comment."
      additionalProperties: false
      required:
        - report
        - text
  
  securitySchemes:
    HogWeedAuth:
      type: apiKey
      name: Authorization
      in: header
      description: 'Header value should be: "Token [TOKEN]"'