ne-student-api.yml

openapi: 3.0.3
info:
  title: Ne Student
  version: 0.1.0
  description: Everything related with ne-student service
  contact:
    name: Yaroslav (API developer)
    email: q.link0.p@gmail.com

externalDocs:
  url: https://github.com/studaco/API-spec
  description: An API repo, containing spec

tags:
  - name: auth
    x-displayName: Authentication API
    description: Authentication APIs, covering needs for login, registration, password reset and token invalidation
  - name: permissions
    x-displayName: Permissions
    description: Manage access to different entities (lessons, teachers, tasks)
  - name: lesson
    x-displayName: Lesson
    description: Everything related to lesson retrieval and manipulation
  - name: teacher
    x-displayName: Teacher
    description: Everything related to teacher retrieval and manipulation
  - name: task
    x-displayName: Task
    description: Everything related to task retrieval and manipulation
  - name: retrieval
    x-displayName: Data fetching
    description: APIs that allow to fetch different entities
  - name: manipulation
    x-displayName: Data manipulation
    description: APIs that allow changing and deleting data resources

x-tagGroups:
  - name: General
    tags:
      - auth
      - permissions
  - name: Entities
    tags:
      - lesson
      - teacher
      - task
  - name: Access types
    tags:
      - retrieval
      - manipulation

servers:
  - url: "http://localhost:8800"

paths:
  /auth/login:
    post:
      tags:
        - auth
      summary: Login user via login and password
      description: Generate access token from login credentials
      operationId: auth-login

      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "out/requests.json#/definitions/Login"
            example:
              $ref: "out/examples.json#/login"

      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "out/responses.json#/definitions/Login"
              example:
                $ref: "out/examples.json#/loginSuccess"
        "400":
          $ref: "#/components/responses/badRequest"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "out/errors.json#/definitions/SingleInvalidCredentials"
              example:
                $ref: "out/examples.json#/invalidCredentials"
        "500":
          $ref: "#/components/responses/internalError"

  /auth/register:
    post:
      tags:
        - auth
      summary: Register a new user
      description: Create a new user
      operationId: auth-register
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "out/requests.json#/definitions/Register"
            examples:
              Fully specified registration:
                value:
                  $ref: "out/examples.json#/register"
              Without last name:
                value:
                  $ref: "out/examples.json#/registerWithoutName"

      responses:
        "200":
          description: Ok
          content:
            application/json:
              schema:
                $ref: "out/responses.json#/definitions/Register"
              examples:
                Success:
                  value:
                    $ref: "out/examples.json#/registerSuccess"
        "400":
          $ref: "#/components/responses/badRequest"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "out/errors.json#/definitions/Register401"
              examples:
                User does not exist:
                  value:
                    $ref: "out/examples.json#/registerFailure"
                Login contains invalid sequence of characters:
                  value:
                    $ref: "out/examples.json#/invalidLogin"
                Password contains invalid sequence of characters:
                  value:
                    $ref: "out/examples.json#/invalidPassword"
        "500":
          $ref: "#/components/responses/internalError"

  /auth/refresh:
    post:
      tags:
        - auth
      summary: Acquire new access token
      description: | 
        Generate access token from login credentials. The old refresh token is then revoked and can't be used again 
        to preform refresh. Refresh token rotation is performed.
      operationId: auth-refresh

      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "out/requests.json#/definitions/RefreshTokens"
            example:
              $ref: "out/examples.json#/refresh"

      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "out/responses.json#/definitions/Refresh"
              example:
                $ref: "out/examples.json#/refreshSuccess"
        "400":
          $ref: "#/components/responses/badRequest"
        "401":
          $ref: "#/components/responses/unauthorized"
        "500":
          $ref: "#/components/responses/internalError"
    
  /auth/revoke:
    post:
      tags:
        - auth
      operationId: auth-revoke
      security:
        - bearerAuth: []
      summary: Revoke refresh token
      description: |
        Revoke refresh token associated with the access token used to authenticate to this endpoint.

      responses:
        "201":
          description: Revoked (No content)
        "401":
          $ref: "#/components/responses/unauthorized"
        "500":
          $ref: "#/components/responses/internalError"
      


  /lesson:
    parameters:
      - name: Authorization
        in: header
        required: true
        schema: { type: string, format: bearer }

    put:
      tags:
        - lesson
        - manipulation
      summary: Create new Lesson
      description: |
        Create new Lesson. User will be automatically assigned read-write permissions
        to the newly created lesson.
      operationId: put-lesson
      security:
        - bearerAuth: []

      requestBody:
        content:
          application/json:
            schema:
              $ref: "out/requests.json#/definitions/AddLesson"
            example:
              $ref: "out/examples.json#/addLesson"

      responses:
        "201":
          description: Created
          content:
            application/json:
              schema:
                $ref: "out/responses.json#/definitions/NewLesson"
              example:
                $ref: "out/examples.json#/getLesson"
        "400":
          $ref: "#/components/responses/badRequest"
        "401":
          $ref: "#/components/responses/unauthorized"
        "500":
          $ref: "#/components/responses/internalError"

  /lesson/{id}:
    parameters:
      - name: id
        required: true
        in: path
        example: a7262da1-33ed-448c-8b7d-97263d0974f7
        schema:
          $ref: "out/common.json#/definitions/LessonID"
      - name: Authorization
        in: header
        required: true
        schema: { type: string, format: bearer }

    patch:
      tags:
        - lesson
        - manipulation
      summary: Modify existing Lesson
      description: |
        Modifies already present lesson, found by id, by setting appropriate fields to the new values.
        If field is not present in request body, that field in entity is left unchanged.
        If field contains appropriate value, that field in entity is set to the new value.
        If field is set to null, that field will be deleted from the entity.
      operationId: patch-lesson
      security:
        - bearerAuth: []

      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "out/requests.json#/definitions/UpdateLesson"
            example:
              $ref: "out/examples.json#/updateLesson"

      responses:
        "204":
          description: Updated (No content)
        "400":
          $ref: "#/components/responses/badRequest"
        "401":
          $ref: "#/components/responses/unauthorized"
        "403":
          $ref: "#/components/responses/noLessonWriteAccess"
        "500":
          $ref: "#/components/responses/internalError"

    get:
      tags:
        - retrieval
        - lesson
      summary: Fetch a single lesson
      description: Retrieve a lesson by its ID
      operationId: get-lesson
      security:
        - bearerAuth: []

      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "out/responses.json#/definitions/GetLesson"
              example:
                $ref: "out/examples.json#/getLesson"
        "400":
          $ref: "#/components/responses/badRequest"
        "401":
          $ref: "#/components/responses/unauthorized"
        "404":
          $ref: "#/components/responses/lessonNotFound"
        "403":
          $ref: "#/components/responses/noLessonReadAccess"
        "500":
          $ref: "#/components/responses/internalError"

    delete:
      tags:
        - manipulation
        - lesson
      summary: Delete a lesson
      description: Delete a single lesson by its ID
      operationId: delete-lesson
      security:
        - bearerAuth: []

      responses:
        "204":
          description: Deleted (No content)
        "400":
          $ref: "#/components/responses/badRequest"
        "401":
          $ref: "#/components/responses/unauthorized"
        "403":
          $ref: "#/components/responses/noLessonWriteAccess"
        "404":
          $ref: "#/components/responses/lessonNotFound"
        "500":
          $ref: "#/components/responses/internalError"

  /lessons:
    parameters:
      - name: date
        in: query
        schema: { type: string }
        description: Date at which lessons are scheduled. Formatted as ISO-8601 date
        example: 01-16-2001
      - name: Authorization
        in: header
        required: true
        schema: { type: string, format: bearer }

    get:
      tags:
        - retrieval
        - lesson
      summary: Fetch list of lessons
      description: |
        Retrieve list of the lessons, filtered by the query parameters.
        If user doesn't have permissions to read certain lessons, they won't be returned by the API
      operationId: get-lessons
      security:
        - bearerAuth: []

      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "out/responses.json#/definitions/GetLessonList"
              examples:
                Populated list:
                  value:
                    $ref: "out/examples.json#/lessonList"
                No lessons found:
                  value:
                    $ref: "out/examples.json#/emptyList"
        "400":
          $ref: "#/components/responses/badRequest"
        "401":
          $ref: "#/components/responses/unauthorized"
        "500":
          $ref: "#/components/responses/internalError"

  /teacher:
    parameters:
      - name: Authorization
        in: header
        required: true
        schema: { type: string, format: bearer }

    put:
      tags:
        - teacher
        - manipulation
      summary: Create a new teacher
      description: Create a new teacher with first name and optional last name
      operationId: put-teacher
      security:
        - bearerAuth: []

      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "out/requests.json#/definitions/AddTeacher"
            example:
              $ref: "out/examples.json#/addTeacher"

      responses:
        "201":
          description: Created
          content:
            application/json:
              schema:
                $ref: "out/responses.json#/definitions/GetTeacher"
              example:
                $ref: "out/examples.json#/addedTeacher"
        "400":
          $ref: "#/components/responses/badRequest"
        "401":
          $ref: "#/components/responses/unauthorized"
        "500":
          $ref: "#/components/responses/internalError"

  /teacher/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          $ref: "out/common.json#/definitions/TeacherID"
        example: 6b7fda92-581f-4236-8127-cc39e58185a1
      - name: Authorization
        in: header
        required: true
        schema: { type: string, format: bearer }

    get:
      tags:
        - teacher
        - retrieval
      summary: Fetch a single teacher
      description: Retrieve a single teacher object by its id
      operationId: get-teacher
      security:
        - bearerAuth: []

      responses:
        "200":
          description: Ok
          content:
            application/json:
              schema:
                $ref: "out/responses.json#/definitions/GetTeacher"
              example:
                $ref: "out/examples.json#/getTeacher"
        "400":
          $ref: "#/components/responses/badRequest"
        "404":
          $ref: "#/components/responses/teacherNotFound"
        "403":
          $ref: "#/components/responses/noTeacherReadAccess"
        "401":
          $ref: "#/components/responses/unauthorized"
        "500":
          $ref: "#/components/responses/internalError"

    patch:
      tags:
        - teacher
        - manipulation
      summary: Modify already existing teacher
      description: |
        Apply set of patches to the teacher resource. Fields with a new values will replace old ones.
        Fields with nulls will delete old values.
      operationId: patch-teacher
      security:
        - bearerAuth: []

      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "out/requests.json#/definitions/UpdateTeacher"
            example:
              $ref: "out/examples.json#/updateTeacher"

      responses:
        "204":
          description: Updated (No content)
        "400":
          $ref: "#/components/responses/badRequest"
        "404":
          $ref: "#/components/responses/teacherNotFound"
        "403":
          $ref: "#/components/responses/noTeacherWriteAccess"
        "401":
          $ref: "#/components/responses/unauthorized"
        "500":
          $ref: "#/components/responses/internalError"

    delete:
      tags:
        - teacher
        - manipulation
      summary: Delete a teacher
      description: Delete a single teacher by its ID
      operationId: delete-teacher
      security:
        - bearerAuth: []
      
      responses:
        "204":
          description: Deleted (No content)
        "400":
          $ref: "#/components/responses/badRequest"
        "401":
          $ref: "#/components/responses/unauthorized"
        "403":
          $ref: "#/components/responses/noTeacherWriteAccess"
        "404":
          $ref: "#/components/responses/teacherNotFound"
        "500":
          $ref: "#/components/responses/internalError"
      

  /teachers:
    parameters:
      - name: Authorization
        in: header
        required: true
        schema: { type: string, format: bearer }

    get:
      tags:
        - teacher
        - retrieval
      summary: Fetch all accessible teachers
      description: Retrieve all teachers that user has access to
      operationId: get-teachers
      security:
        - bearerAuth: []

      responses:
        "200":
          description: Ok
          content:
            application/json:
              schema:
                $ref: "out/responses.json#/definitions/GetTeacherList"
              example:
                $ref: "out/examples.json#/teacherList"
        "400":
          $ref: "#/components/responses/badRequest"
        "401":
          $ref: "#/components/responses/unauthorized"
        "500":
          $ref: "#/components/responses/internalError"

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: |
        Auth schema on studa requires the use of two tokens: `access_token` and `refresh_token`.
        Both tokens are JWTs and contain information to identify user, token expiration date and signature to prove integrity.
        To determine expiration date it is advised to decode JWT and extract `exp` field which contains UNIX time of expiration.

        Access token is used to authorize user to the resource. Access tokens are short-lived and live only for 5 minutes (subject to change).
        Access token is linked to the refresh token that was used to acquire it. Revoking access token actually revokes refresh token it is associated with.

        Refresh token is used to acquire new access token once that expires (or about to expire).
        Refresh tokens live substantially longer: for 14 days (subject to change).
        Upon requesting new access token API responds with new refresh token. Old refresh token is then revoked.

        Token pair is returned by the `/auth/login` and `/auth/register` API calls.

        When access token is expired or is about to expire call to `/auth/refresh` is required to get new access token.

        Refresh tokens can be revoked by calling an `/auth/revoke` endpoint. Refresh token associated with the access token used to 
        authenticate used to the endpoint will be revoked immediately, access tokens are then left to expire.
        When new refresh request is made with the revoked token, `token_revoked` error will be returned by the API.

        This token is expected to be present in the `Authorization` http header in form of `Bearer <token>`.

        So if the access token returned by the `/auth/login` call is `someLongTokenStringWithNumbersAndWierdSymbols`.
        The `Authorization` header should be `Bearer someLongTokenStringWithNumbersAndWierdSymbols`.

  responses:
    badRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: "out/errors.json#/definitions/SingleBadRequest"
          examples:
            Invalid Body:
              value:
                $ref: "out/examples.json#/badRequestBody"

            Invalid Path:
              value:
                $ref: "out/examples.json#/badRequestPath"

    invalidCredentials:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: "out/errors.json#/definitions/SingleInvalidCredentials"
          examples:
            Invalid Credentials:
              value:
                $ref: "out/examples.json#/loginFailure"

    internalError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: "out/errors.json#/definitions/SingleInternalError"
          examples:
            Internal Server Error:
              value:
                $ref: "out/examples.json#/internalError"

    unauthorized:
      description: Access token is missing, invalid or expired
      content:
        application/json:
          schema:
            $ref: "out/errors.json#/definitions/SingleUnauthorized"
          examples:
            Token is missing:
              value:
                $ref: "out/examples.json#/noTokenPresent"
            Invalid token:
              value:
                $ref: "out/examples.json#/invalidToken"
            Token expired:
              value:
                $ref: "out/examples.json#/tokenExpired"
            Token revoked:
              value:
                $ref: "out/examples.json#/tokenRevoked"

    # Lesson specific components
    lessonNotFound:
      description: Lesson not found
      content:
        application/json:
          schema:
            $ref: "out/errors.json#/definitions/SingleLessonDoesNotExist"
          example:
            $ref: "out/examples.json#/lessonNotFound"

    noLessonReadAccess:
      description: No read access
      content:
        application/json:
          schema:
            $ref: "out/errors.json#/definitions/SingleLessonNoReadAccess"
          example:
            $ref: "out/examples.json#/noLessonReadAccess"

    noLessonWriteAccess:
      description: No read/write access
      content:
        application/json:
          schema:
            $ref: "out/errors.json#/definitions/LessonNoWriteAccess403"
          examples:
            No write access:
              value:
                $ref: "out/examples.json#/noLessonWriteAccess"
            No read access:
              value:
                $ref: "out/examples.json#/noLessonReadAccess"

    # Teacher specific components
    teacherNotFound:
      description: Teacher not found
      content:
        application/json:
          schema:
            $ref: "out/errors.json#/definitions/SingleTeacherDoesNotExist"
          example:
            $ref: "out/examples.json#/teacherNotFound"

    noTeacherReadAccess:
      description: No read access
      content:
        application/json:
          schema:
            $ref: "out/errors.json#/definitions/SingleTeacherNoReadAccess"
          example:
            $ref: "out/examples.json#/noTeacherReadAccess"

    noTeacherWriteAccess:
      description: No read/write access
      content:
        application/json:
          schema:
            $ref: "out/errors.json#/definitions/TeacherNoWriteAccess403"
          examples:
            No write access:
              value:
                $ref: "out/examples.json#/noTeacherWriteAccess"
            No read access:
              value:
                $ref: "out/examples.json#/noTeacherReadAccess"