api.yml

openapi: 3.0.3
info:
  title: ITMO Dating Matchmaker
  version: 0.0.1
servers:
  - url: /api/v1
security:
  - bearerAuth: [USER, ADMIN]
paths:
  /monitoring/healthcheck:
    get:
      tags: [Monitoring]
      summary: Checks if service is alive
      description: Returns 'ok', if service is alive, else we will cry
      security: []
      responses:
        200:
          description: OK
          content:
            text/html:
              schema:
                type: string
                example: ok
  /suggestions:
    get:
      tags: [Suggestions]
      summary: Get suggestions
      description: Returns people suggested for a given person
      parameters:
        - name: limit
          in: query
          description: Maximum count of elements to return
          required: false
          schema:
            type: integer
            format: int64
            default: 20
            minimum: 1
            maximum: 50
            example: 8
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/PersonId"
                uniqueItems: true
        401:
          description: No authentication
          content:
            application/josn:
              schema:
                $ref: "#/components/schemas/GeneralError"
  /people/{target_id}/attitudes:
    post:
      tags: [Suggestions]
      summary: Like or skip a suggestion
      description: Source id is taken from an auth token
      parameters:
        - name: target_id
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/PersonId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Attitude"
      responses:
        204:
          description: Attitude was taken into account
        400:
          description: Source already posted an attitude to target
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GeneralError"
        401:
          description: No authentication
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GeneralError"
        404:
          description: Person is not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GeneralError"
        409:
          description: Attitude was already taken
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GeneralError"
  /people/{target_id}/attitudes/{attitude_kind}:
    post:
      tags: [SOA]
      summary: Like or skip a suggestion
      description: |
        Does the same as /people/{target_id}/attitudes.
        Exists just to defend SOA labs.
      parameters:
        - name: target_id
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/PersonId"
        - name: attitude_kind
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/AttitudeKind"
      responses:
        204:
          description: Attitude was taken into account
        401:
          description: No authentication
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GeneralError"
        404:
          description: Person is not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GeneralError"
        409:
          description: Attitude was already taken
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GeneralError"
  /attitudes:
    delete:
      tags: [SOA]
      summary: Reset attitudes
      description: Removes attitudes from the given person
      security:
        - bearerAuth: [ADMIN]
      parameters:
        - name: source_id
          in: query
          required: true
          schema:
            $ref: "#/components/schemas/PersonId"
      responses:
        204:
          description: Attitudes was reset
        401:
          description: No authentication
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GeneralError"
        404:
          description: Person is not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GeneralError"
  /people/{person_id}/matches:
    get:
      tags: [Suggestions]
      summary: Get person matches
      description: Returns people who mutually liked given person
      parameters:
        - name: person_id
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/PersonId"
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/PersonId"
                uniqueItems: true
        401:
          description: No authentication
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GeneralError"
        403:
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GeneralError"
        404:
          description: Person is not found. Error is available only with admin rights
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GeneralError"
  /statistics/attitudes:
    get:
      tags: [SOA]
      summary: Get attitudes statistics
      description: Returns like/skip counters for each person
      security:
        - bearerAuth: [ADMIN]
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    person_id:
                      $ref: "#/components/schemas/PersonId"
                    likes:
                      type: integer
                      description: Count of people liked by the person
                      format: int32
                      minimum: 0
                    skips:
                      type: integer
                      description: Count of people skipped by the person
                      format: int32
                      minimum: 0
                  required:
                    - person_id
                    - likes
                    - skips
                uniqueItems: true
        401:
          description: No authentication
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GeneralError"
        403:
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GeneralError"
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    PersonId:
      type: integer
      description: A unique key of a person, autogenerated
      format: int64
      minimum: 1
      example: 12345678
    AttitudeKind:
      type: string
      enum:
        - like
        - skip
    Attitude:
      type: object
      properties:
        kind:
          $ref: "#/components/schemas/AttitudeKind"
      required:
        - verdict
    GeneralError:
      type: object
      properties:
        code:
          type: integer
          format: int32
          description: HTTP Status Code
          example: 400
        status:
          type: string
          description: HTTP Status Description
          example: Bad Request
        message:
          type: string
          description: Detailed Message
          example: Username must contain only latin letter
      required:
        - code
        - status
        - message