api.yaml

---
################################################################################
# Please read before updating!                                                 #
#   api.yaml -                                                                 #
#       This is the source of the api spec.  Any api-doc changes should be     #
#       made to this file      .                                               #
#   .api-generated.yaml -                                                      #
#       This is an expanded version of api.yaml since the consuming tools are  #
#       unable to parse YAML anchors. This file is generated using:            #
#         `make api_generated`                                                 #
################################################################################
swagger: '2.0'

program_path_param: &program_path_param
  in: path
  name: program_key
  required: true
  type: string
  description: edX program key
  example: 'uexample-master-of-science'
course_path_param: &course_path_param
  in: path
  name: course_id
  required: true
  type: string
  description: edX course run identifier, or an external course run key
  example: 'course-v1:ExU+Science-101+Fall2050'
format_param: &format_param
  in: query
  name: fmt
  required: false
  type: string
  enum: [json, csv]
  description: format of file to generate
  example: 'json'
program_enrollment_body: &program_enrollment_body
  in: body
  name: body
  required: true
  schema:
    type: array
    items:
      $ref: '#/models/ProgramEnrollmentRequest'
course_enrollment_body: &course_enrollment_body
  in: body
  name: body
  required: true
  schema:
    type: array
    items:
      $ref: '#/models/CourseEnrollmentRequest'
student_key: &student_key
  type: string
  description: >
    Key that uniquely identifies student within organization.
    For data privacy reasons, this cannot be, or include,
    sensitive personal information like a student's official university ID
    number, social security number, or some other government-issued ID number.
program_input_status: &program_input_status
  type: string
  enum:
    - enrolled
    - pending
    - suspended
    - canceled
    - ended
program_output_status: &program_output_status
  type: string
  enum:
    - enrolled
    - pending
    - suspended
    - canceled
    - ended
    - invalid-status
    - duplicated
    - conflict
    - not-found
    - illegal-operation
    - internal-error
course_input_status: &course_input_status
  type: string
  enum:
    - active
    - inactive
course_output_status: &course_output_status
  type: string
  enum:
    - active
    - inactive
    - invalid-status
    - duplicated
    - conflict
    - not-in-program
    - not-found
    - illegal-operation
    - internal-error

################################################################################
#                        Base Endpoint Definitions                             #
################################################################################

endpoints:

  get_program: &get_program
    summary: Get Program
    parameters:
      - *program_path_param
    responses:
      200:
        description: OK
        schema:
          $ref: '#/models/Program'
        examples:
          application/json:
            program_title: Master of Science
            program_key: uexample-master-of-science
            program_url: https://uexample.edx.org/uexample-master-of-science
      403:
        description: User is not authorized to view program.
      404:
        description: Program was not found.

  list_programs: &list_programs
    summary: List programs
    description: List all programs, requires an organization key for non-admins
    parameters:
      - in: query
        name: org
        required: false
        type: string
        description: Organization key
    responses:
      200:
        description: OK
        schema:
          type: array
          items:
            $ref: '#/models/Program'
        examples:
          application/json:
            - program_title: Master of Science
              program_key: uexample-master-of-science
              program_url: https://uexample.edx.org/uexample-master-of-science
      403:
        description: User is not authorized to list specified programs.
      404:
        description: Organization was not found.

  get_job_status: &get_job_status
    summary: Get the status of a job
    parameters:
      - in: path
        name: job_id
        required: true
        type: string
        format: uuid
        description: UUID-4 job identifier
        example: 3869c0d5-e88f-4088-bf1d-409222492869
    responses:
      200:
        description: OK
        schema:
          $ref: '#/models/JobStatus'

  list_program_courses: &list_courses
    summary: List program courses
    parameters:
      - *program_path_param
    responses:
      200:
        description: OK
        schema:
          type: array
          items:
            $ref: '#/models/Course'
        examples:
          application/json:
            - course_id: course-v1:ExU+Science-101+Fall2050,
              external_course_key: ExU-IntroToScience50,
              course_title: Introduction to Science,
              course_url: https://courses.edx.org/course-v1:ExU+Science-101+Fall2050
      403:
        description: User is not authorized to list courses of program.
      404:
        description: Program was not found.

  get_program_enrollments: &get_program_enrollments
    summary: Request program enrollment data
    description: Submit a job to retrieve program enrollment data
    parameters:
      - *program_path_param
      - *format_param
    responses:
      202:
        description: Job submitted.
        schema:
          $ref: '#/models/NewJob'
      403:
        description: User is not authorized to retrieve enrollment of program.
      404:
        description: Program was not found.

  post_program_enrollments: &post_program_enrollments
    summary: Enroll students in a program
    parameters:
      - *program_path_param
      - *program_enrollment_body
    responses:
      200:
        description: All students were successfully listed.
        schema:
          $ref: '#/models/ProgramEnrollmentResult'
        examples:
          application/json:
            student_0128fe4a: pending
            student_aae45c81: enrolled
      207:
        description: Some, but not all, students were successfully listed.
        schema:
          $ref: '#/models/ProgramEnrollmentResult'
        examples:
          application/json:
            student_0128fe4a: pending
            student_aae45c81: conflict
      403:
        description: >
          User is not authorized to modify enrollments for program course.
      404:
        description: >
          Course does not exist within program, or program was not found.
      413:
        description: >
          Payload too large; at most 25 students may be supplied per request.
      422:
        description: None of the students were successfully listed.
        schema:
          $ref: '#/models/ProgramEnrollmentResult'
        examples:
          application/json:
            student_0128fe4a: invalid-status
            student_aae45c81: conflict

  patch_program_enrollments: &patch_program_enrollments
    summary: Modify program enrollments
    parameters:
      - *program_path_param
      - *program_enrollment_body
    responses:
      200:
        description: All students' enrollments were successfully modified.
        schema:
          $ref: '#/models/ProgramEnrollmentResult'
        examples:
          application/json:
            student_0128fe4a: enrolled
            student_aae45c81: canceled
      207:
        description: >
          Some, but not all, students' enrollments were successfully modified.
        schema:
          $ref: '#/models/ProgramEnrollmentResult'
        examples:
          application/json:
            student_0128fe4a: enrolled
            student_aae45c81: not-found
      403:
        description: >
          User is not authorized to modify enrollments for program course.
      404:
        description: >
          Course does not exist within program, or program was not found.
      413:
        description: >
          Payload too large; at most 25 students' enrollments may be modified
          per request.
      422:
        description: >
          None of the students' enrollments were successfully modified.
        schema:
          $ref: '#/models/ProgramEnrollmentResult'
        examples:
          application/json:
            student_0128fe4a: invalid-status
            student_aae45c81: not-found

  get_course_enrollments: &get_course_enrollments
    summary: Request course enrollment data
    description: Submit a job to retrieve course enrollment data
    parameters:
      - *program_path_param
      - *course_path_param
      - *format_param
    responses:
      202:
        description: Job submitted.
        schema:
          $ref: '#/models/NewJob'
      403:
        description: >
          User is not authorized to retrieve enrollments for program course.
      404:
        description: >
          Course does not exist within program, or program was not found.

  post_course_enrollments: &post_course_enrollments
    summary: Enroll students in a course
    parameters:
      - *program_path_param
      - *course_path_param
      - *course_enrollment_body
    responses:
      200:
        description: All students were successfully listed.
        schema:
          $ref: '#/models/CourseEnrollmentResult'
        examples:
          application/json:
            student_0128fe4a: inactive
            student_aae45c81: active
      207:
        description: Some, but not all, students were successfully listed.
        schema:
          $ref: '#/models/CourseEnrollmentResult'
        examples:
          application/json:
            student_0128fe4a: inactive
            student_aae45c81: conflict
      403:
        description: >
          User is not authorized to modify enrollments for program course.
      404:
        description: >
          Course does not exist within program, or program was not found.
      413:
        description: >
          Payload too large; at most 25 students may be supplied per request.
      422:
        description: None of the students were successfully listed.
        schema:
          $ref: '#/models/CourseEnrollmentResult'
        examples:
          application/json:
            student_0128fe4a: invalid-status
            student_aae45c81: conflict

  patch_course_enrollments: &patch_course_enrollments
    summary: Modify course enrollments
    parameters:
      - *program_path_param
      - *course_path_param
      - *course_enrollment_body
    responses:
      200:
        description: All students' enrollments were successfully modified.
        schema:
          $ref: '#/models/CourseEnrollmentResult'
        examples:
          application/json:
            student_0128fe4a: active
            student_aae45c81: inactive
      207:
        description: >
          Some, but not all, students' enrollments were successfully modified.
        schema:
          $ref: '#/models/CourseEnrollmentResult'
        examples:
          application/json:
            student_0128fe4a: active
            student_aae45c81: not-found
      403:
        description: >
          User is not authorized to modify enrollments for program course.
      404:
        description: >
          Course does not exist within program, or program was not found.
      413:
        description: >
          Payload too large; at most 25 students' enrollments may be modified
          per request.
      422:
        description: >
          None of the students' enrollments were successfully modified.
        schema:
          $ref: '#/models/CourseEnrollmentResult'
        examples:
          application/json:
            student_0128fe4a: invalid-status
            student_aae45c81: not-found

  get_course_grades: &get_course_grades
    summary: Request course run grade data
    description: Submit a job to retrieve course run grade data
    parameters:
      - *program_path_param
      - *course_path_param
      - *format_param
    responses:
      202:
        description: Job submitted.
        schema:
          $ref: '#/models/NewJob'
      403:
        description: >
          User is not authorized to retrieve enrollments for program course.
      404:
        description: >
          Course does not exist within program, or program was not found.

  list_program_reports: &list_program_reports
    summary: List program reports
    description: List the reports in a program
    parameters:
      - *program_path_param
      - in: query
        name: min_created_date
        type: date
        description: >
          The ISO-format date used to limit the reports
          returned based on their created date
        required: false
        example: '2019-12-18'


    responses:
      200:
        description: OK
        schema:
          type: array
          items:
            $ref: '#/models/ProgramReport'
      403:
        description: User is not authorized to view program reports.
      404:
        description: Program was not found.


  swagger:
    get:
      operationId: registrar_get_api_docs
      responses:
        200:
          description: OK

  static:
    get:
      responses:
        200:
          description: OK

  login:
    get:
      responses:
        302:
          description: Found

  logout:
    get:
      responses:
        302:
          description: Found


################################################################################
#                              API Information                                 #
################################################################################
info:
  title: Registrar API
  description: |
    Registrar API

basePath: '/api'
produces:
  - application/json
consumes:
  - application/json


################################################################################
#                             Path Config                                      #
################################################################################

paths:

  ### V1 API ###
  '/v1/jobs/{job_id}/':
    get:
      <<: *get_job_status
      operationId: registrar_v1_get_job_status
      tags: ['v1']
  '/v1/programs/':
    get:
      <<: *list_programs
      operationId: registrar_v1_list_programs
      tags: ['v1']
  '/v1/programs/{program_key}/':
    get:
      <<: *get_program
      operationId: registrar_v1_get_program
      tags: ['v1']
  '/v1/programs/{program_key}/courses/':
    get:
      <<: *list_courses
      operationId: registrar_v1_list_courses
      tags: ['v1']
  '/v1/programs/{program_key}/courses/{course_id}/enrollments/':
    get:
      <<: *get_course_enrollments
      operationId: registrar_v1_get_course_enrollments
      tags: ['v1']
    post:
      <<: *post_course_enrollments
      operationId: registrar_v1_post_course_enrollments
      tags: ['v1']
    patch:
      <<: *patch_course_enrollments
      operationId: registrar_v1_patch_course_enrollments
      tags: ['v1']
  '/v1/programs/{program_key}/courses/{course_id}/grades/':
    get:
      <<: *get_course_grades
      operationId: registrar_v1_get_course_grades
      tags: ['v1']
  '/v1/programs/{program_key}/enrollments/':
    get:
      <<: *get_program_enrollments
      operationId: registrar_v1_get_program_enrollments
      tags: ['v1']
    post:
      <<: *post_program_enrollments
      operationId: registrar_v1_post_program_enrollments
      tags: ['v1']
    patch:
      <<: *patch_program_enrollments
      operationId: registrar_v1_patch_program_enrollments
      tags: ['v1']
  '/v1/programs/{program_key}/reports':
    get:
      <<: *list_program_reports
      operationId: registrar_v1_list_program_reports
      tags: ['v1']


  ### V2 API ###
  '/v2/jobs/{job_id}/':
    get:
      <<: *get_job_status
      operationId: registrar_v2_get_job_status
      tags: ['v2']
  '/v2/programs/':
    get:
      <<: *list_programs
      operationId: registrar_v2_list_programs
      tags: ['v2']
  '/v2/programs/{program_key}/':
    get:
      <<: *get_program
      operationId: registrar_v2_get_program
      tags: ['v2']
  '/v2/programs/{program_key}/courses/':
    get:
      <<: *list_courses
      operationId: registrar_v2_list_courses
      tags: ['v2']
  '/v2/programs/{program_key}/courses/{course_id}/enrollments/':
    get:
      <<: *get_course_enrollments
      operationId: registrar_v2_get_course_enrollments
      tags: ['v2']
    post:
      <<: *post_course_enrollments
      operationId: registrar_v2_post_course_enrollments
      tags: ['v2']
    patch:
      <<: *patch_course_enrollments
      operationId: registrar_v2_patch_course_enrollments
      tags: ['v2']
  '/v2/programs/{program_key}/courses/{course_id}/grades/':
    get:
      <<: *get_course_grades
      operationId: registrar_v2_get_course_grades
      tags: ['v2']
  '/v2/programs/{program_key}/enrollments/':
    get:
      <<: *get_program_enrollments
      operationId: registrar_v2_get_program_enrollments
      tags: ['v2']
    post:
      <<: *post_program_enrollments
      operationId: registrar_v2_post_program_enrollments
      tags: ['v2']
    patch:
      <<: *patch_program_enrollments
      operationId: registrar_v2_patch_program_enrollments
      tags: ['v2']
  '/v2/programs/{program_key}/reports':
    get:
      <<: *list_program_reports
      operationId: registrar_v2_list_program_reports
      tags: ['v2']

################################################################################
#     Data Models                                                              #
################################################################################
models:
  Program:
    type: object
    properties:
      program_key:
        type: string
      program_title:
        type: string
      program_url:
        type: string
        format: uri
  Course:
    type: object
    properties:
      course_id:
        type: string
      external_course_key:
        type: string
      course_title:
        type: string
      course_url:
        type: string
        format: uri
  ProgramEnrollmentRequest:
    type: object
    properties:
      student_key: *student_key
      status: *program_input_status
  CourseEnrollmentRequest:
    type: object
    properties:
      student_key: *student_key
      status: *course_input_status
  ProgramEnrollmentResult:
    type: object
    additionalProperties: *program_output_status
    description: Mapping from student_keys to program enrollment statuses
  CourseEnrollmentResult:
    type: object
    additionalProperties: *course_output_status
    description: Mapping from student_keys to course enrollment statuses
  NewJob:
    type: object
    properties:
      job_id:
        type: string
        format: uuid
        description: UUID-4 job identifier
      job_url:
        type: string
        format: uri
        description: URL to get status of job
  JobStatus:
    type: object
    properties:
      created:
        type: string
        format: date-time
        description: The ISO-format date-time that the job was created
      state:
        type: string
        enum: [Queued, In Progress, Canceled, Failed, Succeeded]
      result:
        type: string
        format: uri
        nullable: true
        description: URL to result file; null if result unavailable
  ProgramReport:
    type: object
    properties:
      name:
        type: string
        description: The name of the program report
      created_date:
        type: string
        format: date
        description: >
          The ISO-format date-time that the program report was created
      download_url:
        type: string
        format: uri
        description: URL to download the program report