openapi: 3.0.3
info:
  title: Project Ham API Specification
  version: 0.0.1
  contact:
    name: Project Maintainer
    email: me@hamzantal.pw
  license:
    name: MIT
paths:
  /auth/login:
    post:
      tags:
        - Auth Endpoints
      summary: Attempts to log in a user with credentials, and returns an access token.
      requestBody:
        $ref: '#/components/requestBodies/AuthCredentials'
      responses:
        200:
          description: You have been successfully logged in, and you can use the token to interact with the web server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Token'
        400:
          $ref: '#/components/responses/MalformedBody'
        401:
          $ref: '#/components/responses/InvalidCredentials'
        500:
          $ref: '#/components/responses/ServerError'
  /auth/logout:
    get:
      tags:
        - Auth Endpoints
      summary: Logs out a user, making their access token invalid.
      security:
        - token: [ ]
      responses:
        200:
          description: You have successfully logged out, and the token used to authenticate the request is now revoked/invalid.
          content:
            application/json:
              schema:
                type: object
        400:
          $ref: '#/components/responses/MalformedBody'
        401:
          $ref: '#/components/responses/InvalidToken'
        500:
          $ref: '#/components/responses/ServerError'
  /auth/register:
    post:
      tags:
        - Auth Endpoints
      summary: Creates a new user account that can be used to participate with the website.
      requestBody:
        description: The information for the new user.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisteredUser'
      responses:
        200:
          description: Your account has successfully been created, and you can now log in.
          content:
            application/json:
              schema:
                type: object
        400:
          $ref: '#/components/responses/MalformedBody'
        422:
          $ref: '#/components/responses/Unprocessable'
        500:
          $ref: '#/components/responses/ServerError'

  /users/{username}:
    get:
      tags:
        - User Endpoints
      summary: Get information for a user.
      parameters:
        - name: username
          required: true
          in: path
          schema:
            type: string
      responses:
        200:
          description: Public information for the requested user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
  /users/{username}/posts:
    get:
      tags:
        - User Endpoints
        - Post Endpoints
      parameters:
        - name: username
          required: true
          in: path
          schema:
            type: string
        - $ref: '#/components/parameters/AfterParam'
        - $ref: '#/components/parameters/BeforeParam'
        - $ref: '#/components/parameters/LimitParam'
        - $ref: '#/components/parameters/CountParam'
      summary: Get a list of posts a user has created/submitted.
      responses:
        200:
          description: A list of posts filtered and formatted.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Post'
        400:
          $ref: '#/components/responses/MalformedBody'
        422:
          $ref: '#/components/responses/Unprocessable'
        500:
          $ref: '#/components/responses/ServerError'
  /users/{username}/comments:
    get:
      tags:
        - User Endpoints
        - Comment Endpoints
      parameters:
        - name: username
          required: true
          in: path
          schema:
            type: string
        - $ref: '#/components/parameters/AfterParam'
        - $ref: '#/components/parameters/BeforeParam'
        - $ref: '#/components/parameters/LimitParam'
        - $ref: '#/components/parameters/CountParam'
      summary: Get a list of paginated comments a user has submitted.
      responses:
        200:
          description: A list of comments filtered and formatted.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Comment'
        400:
          $ref: '#/components/responses/MalformedBody'
        422:
          $ref: '#/components/responses/Unprocessable'
        500:
          $ref: '#/components/responses/ServerError'

  /posts:
    get:
      tags:
        - Post Endpoints
      summary: Get a list of paginated posts.
      description: The items retrieved will always show newest first.
      parameters:
        - name: filter
          in: query
          description: Filter posts by content in title and description
          schema:
            type: string
        - $ref: '#/components/parameters/AfterParam'
        - $ref: '#/components/parameters/BeforeParam'
        - $ref: '#/components/parameters/LimitParam'
        - $ref: '#/components/parameters/CountParam'
      responses:
        '200':
          description: A list of posts filtered and formatted.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Post'
        400:
          $ref: '#/components/responses/MalformedBody'
        422:
          $ref: '#/components/responses/Unprocessable'
        500:
          $ref: '#/components/responses/ServerError'
  /posts/new:
    post:
      tags:
        - Post Endpoints
      security:
        - token: [ ]
      summary: Submit a new comment.
      description: This endpoint will take information that new comments require, a post ID, and ssubmits a comment to a post.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
                - content
                - parent
              properties:
                title:
                  description: The title of the post created
                  type: string
                description:
                  description: The body text of a post, optional.
            example:
              title: I use arch BTW.
              description: Ladies, I'm waiting.
      responses:
        200:
          description: The created post ID
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
        400:
          $ref: '#/components/responses/MalformedBody'
        401:
          $ref: '#/components/responses/InvalidToken'
        422:
          $ref: '#/components/responses/Unprocessable'
        500:
          $ref: '#/components/responses/ServerError'
  /post/{id}:
    get:
      tags:
        - Post Endpoints
      summary: Get information for a post.
      description: Returns the post information and all comments for a particular post.
      parameters:
        - name: id
          in: path
          required: true
          description: The post ID to retrieve information about
          schema:
            type: string
      responses:
        200:
          description: Information regarding a post
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/Post'
                  - type: object
                    required:
                      - comments
                    properties:
                      comments:
                        type: array
                        items:
                          $ref: '#/components/schemas/Comment'
        404:
          $ref: '#/components/responses/NotFound'
        500:
          $ref: '#/components/responses/ServerError'
  /post/{id}/upvote:
    post:
      tags:
        - Post Endpoints
      summary: Upvote a post.
      description: Add an upvote to a specified post. If you have already upvoted a point, it is retracted.
      security:
        - token: []
      parameters:
        - name: id
          in: path
          required: true
          description: The post ID to upvote.
          schema:
            type: string
      responses:
        200:
          description: Your upvote has successfully been registered.
          content:
            application/json:
              schema:
                type: object
        401:
          $ref: '#/components/responses/InvalidToken'
        404:
          $ref: '#/components/responses/NotFound'
        500:
          $ref: '#/components/responses/ServerError'
  /post/{id}/downvote:
    post:
      tags:
        - Post Endpoints
      summary: Downvote a post
      description: Add an downvote to a specified post. If you have already downvoted a point, it is retracted.
      security:
        - token: []
      parameters:
        - name: id
          in: path
          required: true
          description: The post ID to downvote.
          schema:
            type: string
      responses:
        200:
          description: Your downvote has successfully been registered.
          content:
            application/json:
              schema:
                type: object
        401:
          $ref: '#/components/responses/InvalidToken'
        404:
          $ref: '#/components/responses/NotFound'
        500:
          $ref: '#/components/responses/ServerError'

  /comment/new:
    post:
      tags:
        - Comment Endpoints
      security:
        - token: [ ]
      summary: Submit a comment.
      description: This endpoint will take information that new posts require and then create a new entry that will be submitted to the website.
      requestBody:
        description: Submit a new post with this endpoint.
        required: true
        content:
          application/json:
            schema:
              required:
                - content
                - post_id
              properties:
                content:
                  description: The message of the comment
                  type: string
                post_id:
                  description: The id of the post the comment belongs to.
                parent_id:
                  description: The parent comment. If not provided, interpreted as a top-level comment.
            example:
              content: No one cares about arch!
              post_id: a1b2c3d4
      responses:
        200:
          description: The created comment ID
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
        400:
          $ref: '#/components/responses/MalformedBody'
        401:
          $ref: '#/components/responses/InvalidToken'
        422:
          $ref: '#/components/responses/Unprocessable'
        500:
          $ref: '#/components/responses/ServerError'
  /comment/{id}/upvote:
    post:
      tags:
        - Comment Endpoints
      summary: Upvote a comment.
      description: Add an upvote to a specified comment. If you have already upvoted a point, it is retracted.
      security:
        - token: []
      parameters:
        - name: id
          in: path
          required: true
          description: The comment ID to upvote.
          schema:
            type: string
      responses:
        200:
          description: Your upvote has successfully been registered.
          content:
            application/json:
              schema:
                type: object
        401:
          $ref: '#/components/responses/InvalidToken'
        404:
          $ref: '#/components/responses/NotFound'
        500:
          $ref: '#/components/responses/ServerError'
  /comment/{id}/downvote:
    post:
      tags:
        - Comment Endpoints
      summary: Downvote a comment
      description: Add an downvote to a specified comment. If you have already downvoted a point, it is retracted.
      security:
        - token: []
      parameters:
        - name: id
          in: path
          required: true
          description: The comment ID to downvote.
          schema:
            type: string
      responses:
        200:
          description: Your downvote has successfully been registered.
          content:
            application/json:
              schema:
                type: object
        401:
          $ref: '#/components/responses/InvalidToken'
        404:
          $ref: '#/components/responses/NotFound'
        500:
          $ref: '#/components/responses/ServerError'
components:
  parameters:
    AfterParam:
      name: after
      in: query
      description: Date after which to return items.
      schema:
        type: string
        format: 'date-time'
        example: 2020-01-01T00:00:00.000z
    BeforeParam:
      name: before
      in: query
      description: Date before which to return items.
      schema:
        type: string
        format: 'date-time'
        example: 2030-01-01T00:00:00.000z
    LimitParam:
      name: limit
      in: query
      description: Maximum number of items to return
      schema:
        type: integer
        maximum: 100
        minimum: 0
    CountParam:
      name: count
      in: query
      description: The number of items already seen in this listing. Items will always be sorted by newest first.
      schema:
        type: integer
        default: 0
        minimum: 0

  requestBodies:
    AuthCredentials:
      description: User credentials.
      required: true
      content:
        application/json:
          schema:
            required:
              - username
              - password
            type: object
            properties:
              username:
                description: The username of the user.
                type: string
              password:
                description: The password of the user.
                type: string
  responses:
    MalformedBody:
      description: The information in your body is incomplete, or your JSON format is invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            reason: Invalid request body provided.
            code: 400
    InvalidCredentials:
      description: The credentials you have provided are incorrect.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            reason: The username or password provided are incorrect.
            code: 401
    InvalidToken:
      description: The access token you provided is invalid or missing.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            reason: The token provided is invalid.
            code: 401
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            reason: The specified resource does not exist.
            code: 404
    Unprocessable:
      description: The request was valid, however some of the parameters have an invalid value.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            reason: Varies
            code: 422
    ServerError:
      description: The server could not complete a request due to an unknown error. More information may be available in the 'reason' parameter.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            reason: The internal server reached an unknown state.
            code: 500
  schemas:
    RegisteredUser:
      type: object
      required:
        - username
        - email
        - password
      properties:
        username:
          description: A unique username to identify a user around the website.
          type: string
          minLength: 3
          maxLength: 16
          pattern: "[a-zA-Z0-9 ]{3,16}"
        email:
          description: A unique email used for communication/further identification.
          type: string
          format: email
        password:
          type: string
          format: password
          minLength: 8
          maxLength: 32
    User:
      type: object
      required:
        - id
        - username
        - points
        - date_created
      properties:
        id:
          type: string
          description: The unique ID of the user
        username:
          type: string
          description: The username of the user
        points:
          type: number
          description: The number of points (sum of upvotes and downvotes) of a user
        date_created:
          type: string
          format: 'date-time'
          description: "When the user's account was created"
    Token:
      required:
        - token
      type: object
      properties:
        token:
          description: The access token value.
          type: string
    Post:
      type: object
      required:
        - id
        - user_id
        - title
        - upvotes
        - downvotes
        - comments
        - date_created
      properties:
        id:
          description: The unique ID of a post.
          type: string
        user_id:
          description: The ID of the user who created the post.
          type: string
        title:
          description: The main title of a post.
          type: string
        description:
          description: The body text of a post, optional.
          type: string
        upvotes:
          description: The number of upvotes a post has.
          type: integer
        downvotes:
          description: The number of downvotes a post has.
          type: integer
        comments:
          description: The number of comments available on a post.
          type: integer
        date_created:
          description: The time at which this post was submitted.
          type: string
          format: 'date-time'
    Comment:
      type: object
      required:
        - id
        - user_id
        - post_id
        - content
        - upvotes
        - downvotes
        - date_created
      properties:
        id:
          description: The unique ID of a comment.
          type: string
        user_id:
          description: The ID of the user who posted the comment.
          type: string
        post_id:
          description: The ID of the post this comment is created under.
          type: string
        parent_id:
          description: The ID of the parent comment this comment is created to, if not provided, a top-level comment.
          type: string
        content:
          description: The content/message of a comment.
          type: string
        upvotes:
          description: The number of upvotes a comment has.
          type: integer
        downvotes:
          description: The number of downvotes a comment has.
          type: integer
        date_created:
          description: The time at which this comment was submitted.
          type: string
          format: 'date-time'
    Error:
      required:
        - reason
        - code
      type: object
      properties:
        reason:
          description: The cause of the error message.
          type: string
        code:
          description: The HTTP error code value accompanying the error.
          type: integer
  securitySchemes:
    token:
      type: http
      scheme: bearer