APIs.yaml

swagger: "2.0"
info:
  description: |
    OpenChat application used by Robert C. Martin and Sandro Mancuso in their Clean Coders series.
  version: "1.0.0"
  title: OpenChat
  termsOfService: http://codurance.com/
  contact:
    name: sandro@codurance.com
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
host: localhost:4321
basePath: /v2
schemes:
  - http
paths:

  /users:
    post:
      tags:
        - registration
      summary: Register a new user.
      description: ""
      operationId: registration
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: body
          name: body
          description: New user information
          required: true
          schema:
            $ref: "#/definitions/Registration"
      responses:
        "201":
          description: User created.
          schema:
            $ref: "#/definitions/User"
        "400":
          description: Username already in use.
    get:
      tags:
        - user
      summary: Return all users.
      operationId: allUsers
      produces:
        - application/json
      responses:
        "200":
          description: Successful operation
          schema:
            type: array
            items:
              $ref: "#/definitions/User"

  /login:
    post:
      tags:
        - login
      summary: User login
      description: ""
      operationId: login
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: body
          name: body
          description: user credentials
          required: true
          schema:
            $ref: "#/definitions/Login"
      responses:
        "200":
          description: User logged in.
          schema:
            $ref: "#/definitions/User"
        "404":
          description: Invalid credentials.

  /users/{userId}/timeline:
    post:
      tags:
        - post
      summary: Create a new post. All posts are moderated. Posts containing inappropriate language will be refused. For now, words considered inappropriated are - orange, ice cream, elephant. More will be added in the future.
      operationId: createPost
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: path
          name: userId
          description: ID of the user creating the post.
          required: true
          type: string
          format: UUID
        - in: body
          name: body
          description: Post text
          required: true
          schema:
            $ref: "#/definitions/NewPost"
      responses:
        "201":
          description: Post created.
          schema:
            $ref: "#/definitions/Post"
        "400":
          description: Post contains inappropriate language.
        "404":
          description: User not found.
    get:
      tags:
        - post
      summary: Return the user's timeline. The timeline contains only posts from that specific user. Posts are in reverse chronological order.
      operationId: timeline
      produces:
        - application/json
      parameters:
        - in: path
          name: userId
          description: ID of the user we want the timeline.
          required: true
          type: string
          format: UUID
      responses:
        "200":
          description: Successful operation
          schema:
            type: array
            items:
              $ref: "#/definitions/Post"
        "404":
          description: User not found.

  /followings:
    post:
      tags:
        - user
      summary: Create a following relationship between users.
      operationId: following
      consumes:
        - application/json
      parameters:
        - in: body
          name: body
          description: Following information
          required: true
          schema:
            $ref: "#/definitions/Follow"
      responses:
        "201":
          description: Following created.
        "400":
          description: Following already exist.

  /followings/{followerId}/followees:
    get:
      tags:
        - user
      summary: Return users followed by a given user.
      operationId: followees
      produces:
        - application/json
      parameters:
        - in: path
          name: followerId
          description: ID of the follower user.
          required: true
          type: string
          format: UUID
      responses:
        "200":
          description: Successful operation
          schema:
            type: array
            items:
              $ref: "#/definitions/User"

  /users/{userId}/wall:
    get:
      tags:
        - post
      summary: Return the user's wall. The wall contains posts from the user itself and post from user's followees. Posts are in reverse chronological order.
      operationId: wall
      produces:
        - application/json
      parameters:
        - in: path
          name: userId
          description: ID of the user we want the wall.
          required: true
          type: string
          format: UUID
      responses:
        "200":
          description: Successful operation
          schema:
            type: array
            items:
              $ref: "#/definitions/Post"
        "404":
          description: User not found.

definitions:
  Registration:
    type: object
    properties:
      username:
        type: string
      password:
        type: string
      about:
        type: string

  Login:
    type: object
    properties:
      username:
        type: string
      password:
        type: string

  User:
    type: object
    properties:
      id:
        type: string
        format: UUID
        description: UUID
        example: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
      username:
        type: string
      about:
        type: string

  NewPost:
    type: object
    properties:
      text:
        type: string
        example: "Hello, I'm Alice"

  Post:
    type: object
    properties:
      postId:
        type: string
        format: UUID
        description: UUID
        example: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
      userId:
        type: string
        format: UUID
        description: UUID
        example: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
      text:
        type: string
      dateTime:
        type: string
        format: date-time
        description: "yyyy-MM-ddTHH:mm:ssZ"
        example: "2018-01-10T11:30:00Z"

  Follow:
    type: object
    properties:
      followerId:
        type: string
        format: UUID
        description: UUID
        example: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
      followeeId:
        type: string
        format: UUID
        description: UUID
        example: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx