users-api-v1.yaml

openapi: 3.0.3
info:
  version: 0.1.0
  title: Monki Projects' Users API
servers:
  - description: Monki Projects' Users API v1 (production)
    url: 'https://api.monkiprojects.com/users/v1'
  - description: Monki Projects' Users API v1 (staging / development)
    url: 'https://staging.api.monkiprojects.com/users/v1'
tags:
  - name: users
    description: Endpoints related to users.
paths:
  '/':
    post:
      summary: Create User
      description: Creates a user.
      operationId: createUser
      tags:
        - users
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User.Create'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User.Private'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: 'schemas.yaml#/Error'
              examples:
                InvalidEmail:
                  value:
                    error: true
                    reason: Your email address is invalid.
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '409':
          description: Conflict with other user
          content:
            application/json:
              schema:
                $ref: 'schemas.yaml#/Error'
              examples:
                UsernameNotAvailable:
                  value:
                    error: true
                    reason: Email or username already taken
                EmailNotAvailable:
                  value:
                    error: true
                    reason: Email or username already taken
    get:
      summary: List Users
      description: Returns the list of all users.
      operationId: listUsers
      tags:
        - users
      parameters:
        - $ref: 'parameters.yaml#/PaginatePage'
        - $ref: 'parameters.yaml#/PaginatePerPage'
        # - $ref: '#/components/parameters/UsersOrder'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsersPage'
  '/{userId}':
    get:
      summary: Get User Details
      description: Returns details about a particular user.
      operationId: getUser
      tags:
        - users
      parameters:
        - $ref: '#/components/parameters/UserId'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User.Public.Full'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: 'schemas.yaml#/Error'
              examples:
                User not found:
                  value:
                    error: true
                    reason: User not found.
        '422':
          description: Bad user ID
          content:
            application/json:
              schema:
                $ref: 'schemas.yaml#/Error'
              examples:
                Unprocessable Entity:
                  value:
                    error: true
                    reason: Unprocessable Entity
    delete:
      summary: Delete User
      description: Deletes a user.
      operationId: deleteUser
      tags:
        - users
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/UserId'
      responses:
        '204':
          description: Success
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          description: User ID malformatted
          content:
            application/json:
              schema:
                $ref: 'schemas.yaml#/Error'
              examples:
                Unprocessable Entity:
                  value:
                    error: true
                    reason: Unprocessable Entity
components:
  schemas:
    # ===== Atoms =====
    User.ID:
      $ref: 'schemas.yaml#/ID'
    User.Username:
      description: A username (`@`).
      type: string
      minLength: 3
      maxLength: 32
      pattern: '^[a-z0-9._-]{3,32}$'
      example: lorem_ipsum
    User.DisplayName:
      description: A user display name.
      type: string
      minLength: 3
      maxLength: 32
      # TODO: Add pattern
      example: Lorem Ipsum
    User.Country:
      description: The country of a user. Will generally show as a flag next to the user's display name.
      type: string
      # TODO: Add pattern
      example: FR
    User.Kind:
      description: The kind of a user. Either a regular user or a bot.
      type: string
      enum: [user, bot]
      default: user
    User.Bio:
      description: A user's bio (profile description).
      type: string
    User.Location:
      description: A user's location. It's not formatted nor checked as an existing place, so it could be anything.
      type: string

    # ===== Molecules =====
    User.Experience:
      type: object
      # TODO: Describe Dictionary
    User.SocialUsernames:
      type: object
      # TODO: Describe Dictionary

    # ===== Organisms =====
    User.Public.Small:
      description: Public informations about a user (only required ones).
      type: object
      required: [id, username, display_name, kind, updated_at]
      properties:
        id:
          $ref: '#/components/schemas/User.ID'
        username:
          $ref: '#/components/schemas/User.Username'
        display_name:
          $ref: '#/components/schemas/User.DisplayName'
        avatar:
          $ref: 'schemas.yaml#/AvatarSource'
        country:
          $ref: '#/components/schemas/User.Country'
        kind:
          $ref: '#/components/schemas/User.Kind'
        updated_at:
          $ref: 'schemas.yaml#/DateTime'
    User.Details:
      description: Details about a user.
      type: object
      required: [experience, social_usernames, created_at]
      properties:
        bio:
          $ref: '#/components/schemas/User.Bio'
        location:
          $ref: '#/components/schemas/User.Location'
        experience:
          $ref: '#/components/schemas/User.Experience'
        social_usernames:
          $ref: '#/components/schemas/User.SocialUsernames'
        created_at:
          $ref: 'schemas.yaml#/DateTime'
    User.Public.Full:
      description: Public informations about a user (including all details).
      type: object
      required: [id, username, display_name, kind, updated_at, details]
      properties:
        id:
          $ref: '#/components/schemas/User.ID'
        username:
          $ref: '#/components/schemas/User.Username'
        display_name:
          $ref: '#/components/schemas/User.DisplayName'
        avatar:
          $ref: 'schemas.yaml#/AvatarSource'
        country:
          $ref: '#/components/schemas/User.Country'
        kind:
          $ref: '#/components/schemas/User.Kind'
        updated_at:
          $ref: 'schemas.yaml#/DateTime'
        details:
          $ref: '#/components/schemas/User.Details'
    User.Private:
      description: Private details about a user.
      type: object
      required: [id, username, display_name, kind, updated_at, details, email]
      properties:
        id:
          $ref: '#/components/schemas/User.ID'
        username:
          $ref: '#/components/schemas/User.Username'
        display_name:
          $ref: '#/components/schemas/User.DisplayName'
        avatar:
          $ref: 'schemas.yaml#/AvatarSource'
        country:
          $ref: '#/components/schemas/User.Country'
        kind:
          $ref: '#/components/schemas/User.Kind'
        updated_at:
          $ref: 'schemas.yaml#/DateTime'
        details:
          $ref: '#/components/schemas/User.Details'
        email:
          $ref: 'schemas.yaml#/Email'
    User.Create:
      description: Informations required to create a user.
      type: object
      required: [username, display_name, email, password, confirm_password]
      properties:
        username:
          $ref: '#/components/schemas/User.Username'
        display_name:
          $ref: '#/components/schemas/User.DisplayName'
        email:
          $ref: 'schemas.yaml#/Email'
        password:
          $ref: 'schemas.yaml#/Password'
        confirm_password:
          $ref: 'schemas.yaml#/Password'
      example:
        username: vapor
        display_name: Vapor
        email: test@vapor.codes
        password: password
        confirm_password: password

    # ===== Arrays =====
    ArrayOfUsers:
      description: An array of users (without unnecessary details).
      type: array
      items:
        $ref: '#/components/schemas/User.Public.Small'

    # ===== Pagination =====
    # === Paginated Arrays ===
    UsersPage:
      description: A paginated array of users.
      type: object
      required: [items, metadata]
      properties:
        items:
          $ref: '#/components/schemas/ArrayOfUsers'
        metadata:
          $ref: 'schemas.yaml#/PaginateMetadata'
    # === Ordering ===
    # UsersOrder:
    #   description: >-
    #     The order of the users in an array:
    #       * `last_joined`: From the latest created review to the oldest one
    #       * `first_joined`: From the first created review to the latest one
    #   type: string
    #   enum: [last_joined, first_joined]
  responses:
    UnauthorizedError:
      description: Authentication information is missing or is invalid.
      content:
        application/json:
          schema:
            $ref: 'schemas.yaml#/Error'
          examples:
            Unauthorized:
              value:
                error: true
                reason: Unauthorized
  parameters:
    UserId:
      in: path
      name: userId
      description: A user ID.
      required: true
      schema:
        $ref: 'schemas.yaml#/ID'
    # UsersOrder:
    #   in: query
    #   name: sort_by
    #   description: The results order. If not set, results won't be ordered.
    #   schema:
    #     $ref: '#/components/schemas/UsersOrder'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer