swagger.yaml

swagger: '2.0'

info:
  version: '1.0.0'
  title: 'Friends Microservice'
  description: 'Microservice for creating friends between users.'
  contact:
    name: Jarrod Parkes
    email: jarrod@udacity.com
    url: http://jarrodparkes.com
  license:
    name: MIT License
    
schemes:
  - https
consumes:
  - application/json
produces:
  - application/json

paths:
  /users/friends:
    delete:
      description: Remove users from the current user's friend list.
      summary: Remove users from the current user's friend list.
      parameters:
        - name: friend_ids
          in: body
          description: Users to remove from friend's list.
          required: true
          schema:
            $ref: '#/definitions/RemoveUsers'  
      responses:
          204:
            description: Event deleted.
            schema:
              $ref: '#/definitions/Message'
          304:
            $ref: "#/responses/NotModified"              
          400:
            description: Bad request.
            schema:
              $ref: '#/definitions/Message'           
          401:
            $ref: "#/responses/Unauthorized"
      security:
        - JWT: []             
  /users/{id}/friends:
    get:
      description: List a user's friends.
      summary: List a user's friends.
      parameters:
        - name: id
          in: path
          description: ID of user to fetch.
          required: true
          type: integer
          format: int64  
        - name: page_size
          in: query
          description: Number of events returned. Limit is 50.
          type: integer
          default: 10
        - name: page_number
          in: query
          description: Page number.
          type: integer
          default: 1          
      responses:
        200:
          description: Successful response.
          schema:
            type: array
            items:
              $ref: '#/definitions/Friends'
        400:
          $ref: "#/responses/BadRequest"
        401:
          $ref: "#/responses/Unauthorized"
        404:
          $ref: "#/responses/NotFound"
  /users/invites:
    get:
      description: List friend invitations for the current user.
      summary: List friend invitations for the current user.
      parameters:
        - name: page_size
          in: query
          description: Number of events returned. Limit is 50.
          type: integer
          default: 10
        - name: page_number
          in: query
          description: Page number.
          type: integer
          default: 1
      responses:
        200:
          description: Successful response.
          schema:
            type: array
            items:
              $ref: '#/definitions/Invitation'
        401:
          description: Unauthorized request.
          schema:
            $ref: '#/definitions/Message'   
      security:
        - JWT: []             
    post:
      description: Send friend invitations from the current user.
      summary: Send friend invitations from the current user.
      parameters:
        - name: filter
          in: body
          description: Users to invite.
          required: true
          schema:
            type: object
            properties:
              user_ids:
                type: array
                items:
                  type: string
                  default: "2"
            required:
              - user_ids
      security:
        - JWT: []               
      responses:
        201:
          description: Resource created.
          schema:
            $ref: '#/definitions/Message'
        400:
          $ref: "#/responses/BadRequest"
        401:
          $ref: "#/responses/Unauthorized"
        404:
          $ref: "#/responses/NotFound"
  /users/invites/search:
    get:
      description: List and filter friend invitations for the current user.
      summary: List and filter friend invitations for the current user.
      parameters:
       - name: page_size
         in: query
         description: Number of events returned. Limit is 50.
         type: integer
         default: 10
       - name: page_number
         in: query
         description: Page number.
         type: integer
         default: 1
       - name: type
         in: query
         description: Type of invitations to filter (inviter|invitee|all).
         type: string
         default: "all"         
      responses:
        200:
          description: Successful response.
          schema:
            type: array
            items:
              $ref: '#/definitions/Invitation'
        401:
          description: Unauthorized request.
          schema:
            $ref: '#/definitions/Message'   
      security:
        - JWT: []          
  /users/invites/{id}:
    put:
      description: Update a friend invitation for the current user.
      summary: Update a friend invitation for the current user.
      parameters:
        - name: id
          in: path
          description: ID of invitation to update.
          required: true
          type: integer
          format: int64 
        - name: invitation_response
          in: body
          description: Response to invitation.
          required: true
          schema:
            type: object
            properties:
              accepted:
                type: boolean
                default: true
            required:
              - accepted          
      responses:
        200:
          description: Invite accepted or declined.
          schema:
            $ref: '#/definitions/Message'
        304:
          $ref: "#/responses/NotModified"            
        400:
          description: Bad request.
          schema:
            $ref: '#/definitions/Message'
        401:
          $ref: "#/responses/Unauthorized"    
      security:
        - JWT: []           

responses:
  NoContent:
    description: The request was fulfilled, but nothing to return.
  BadRequest:
    description: Invalid request.
  NotModified:
    description: The specified resource was not modified.
  NotFound:
    description: The specified resource was not found.
  Unauthorized:
    description: Unauthorized.

securityDefinitions:
  JWT:
    type: apiKey
    description: A Base64-encoded JSON web token.
    name: "Authorization: Bearer"
    in: header

definitions:
  Friends:
    type: object
    properties:
      friend_id:
        type: string
        description: ID of friend record.
        default: "1"
      user_id:
        type: string
        description: ID of user.
        default: "2"
      friend_user_id:
        type: string
        description: ID of befriended user.
        default: "3"
    required:
      - friend_id
      - user_id
      - friend_user_id
  Invitation:
    type: object
    properties:
      inviter_user_id:
        type: string
        description: IDs of users invited to become friends.
      invitee_user_id:
        type: string
        description: IDs of users invited to become friends.
    required:
      - invite_user_id
      - invitee_user_id
    default:
      inviter_user_id: "2"
      invitee_user_id: "3"
  RemoveUsers:
    type: object
    properties:
      friend_ids:
        type: array
        description: IDs of users to remove to friend's list.
        readOnly: true
        items:
          type: string
          default: "4"
    required:
      - friend_ids
  Message:
    type: object
    properties:
      message:
        type: string
        description: A message.
    required:
      - message
    example:
      message: "A message describing the HTTP status code."