project-ham/api/swagger.yaml

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: Attemps 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:
    post:
      tags:
        - Auth Endpoints
      summary: Logs out a user, making their access token invalid.
      requestBody:
        $ref: '#/components/requestBodies/TokenRequest'
      responses:
        200:
          description: You have successfully logged out, and your token is now 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'
        401:
          $ref: '#/components/responses/InvalidToken'
        500:
          $ref: '#/components/responses/ServerError'

  /users/{username}:
    get:
      tags:
        - User Endpoints
      summary: Get the 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
        - Posts Endpoints
      summary: Get the list of posts a user has created/submitted.
      requestBody:
        $ref: '#/components/requestBodies/Listing'
      responses:
        200:
          description: A list of posts filtered and formatted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Post'
        400:
          $ref: '#/components/responses/MalformedBody'
        422:
          $ref: '#/components/responses/Unprocessable'
        500:
          $ref: '#/components/responses/ServerError'

components:
  requestBodies:
    AuthCredentials:
      description: User credentials.
      required: true
      content:
        application/json:
          schema:
            required:
              - username
              - password
            type: object
            properties:
              username:
                type: string
                description: The username of the user.
              password:
                type: string
                description: The password of the user.
    TokenRequest:
      description: The access token to identify a user.
      content:
        application/json:
          schema:
            required:
              - token
            properties:
              token:
                type: string
                description: The access token.
    Listing:
      description: Query particular data sorted by date and time.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Listing'
  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
    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 informatino may be available in the description.
      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:
          type: string
          minLength: 3
          maxLength: 16
          pattern: "[a-zA-Z0-9 ]{3,16}"
          description: A Unique uusername to identify a user around the website.
        email:
          type: string
          format: email
          description: A Unique email used for communication/further identification.
        password:
          type: string
          format: password
          minLength: 8
          maxLength: 32
    User:
      type: object
      required:
        - id
        - username
        - points
        - date_created
    Token:
      required:
        - token
      type: object
      properties:
        token:
          type: string
          description: The access token value
    Post:
      type: object
      required:
        - id
        - user_id
        - title
        - description
        - upvotes
        - downvotes
    Error:
      required:
        - reason
        - code
      type: object
      properties:
        reason:
          type: string
          description: The cause of the error message
        code:
          type: integer
          description: The HTTP error code value accompanying the error.
    Listing:
      type: object
      properties:
        after:
          type: string
          format: 'date-time'
          description: Filter items to only return those after this date and time.
          default: 2020-01-01T00:00:00.000z
        before:
          type: string
          format: 'date-time'
          description: Filter items to only return those before this date and time.
          default: 2030-01-01T00:00:00.000z
        count:
          type: integer
          description: The number of items already seen in this listing. Items will always be sorted by newest first.
          default: 0
        limit:
          type: integer
          maximum: 100
          description: The maximum number of items to provide. Can be used in conjunction with 'count' to paginate.
          default: 10
      example:
        after: 2020-01-01T00:00:00.000z
        before: 2030-01-01T00:00:00.000z
        count: 0
        limit: 10