api-compact.yaml

# Enterprise Access IDA: upstream API definitions, including vendor extensions.
# Note, while this document is not strictly to Swagger spec, each HTTP method's
# definition _must_ be to spec or the downstream ref will fail.
#
# Clients must include an Authorization header with OAuth2 access token in order to communicate:
#   Authorization: JWT {access_token}
#
#
# Available service endpoints -- note that alternate endpoints may be presented at the API Gateway tier
# POST  /api/v1/policy-allocation/{policy_uuid}/allocate/
# GET   /api/v1/assignment-configurations/{assignment_configuration_uuid}/admin/assignments/
# POST  /api/v1/assignment-configurations/{assignment_configuration_uuid}/admin/assignments/remind/
# POST  /api/v1/assignment-configurations/{assignment_configuration_uuid}/admin/assignments/cancel/
# GET   /api/v1/subsidy-access-policies/

apigateway_responses: &apigateway_responses
  default:
    statusCode: "400"
  200:
    statusCode: "200"
  201:
    statusCode: "201"
  202:
    statusCode: "202"
  401:
    statusCode: "401"
  403:
    statusCode: "403"
  404:
    statusCode: "404"
  422:
    statusCode: "422"
  429:
    statusCode: "429"
  500:
    statusCode: "500"


learner_content_assignment_list_remind_cancel_responses: &learner_content_assignment_list_remind_cancel_responses
  200:
    description: "OK"
  400:
    description: "Bad Request"
  401:
    description: "Unauthorized"
  403:
    description: "Forbidden"
  404:
    description: "Not Found"
  422:
    description: "Not Cancellable"
  500:
    description: "Internal Server Error"

learner_content_assignment_allocate_responses: &learner_content_assignment_allocate_responses
  202:
    description: "Accepted"
  400:
    description: "Bad Request"
  401:
    description: "Unauthorized"
  404:
    description: "Not Found"
  500:
    description: "Internal Server Error"


assignment_configuration_uuid: &assignment_configuration_uuid
  name: "assignment_configuration_uuid"
  in: "path"
  required: true
  type: "string"

auth_header: &auth_header
  name: "Authorization"
  in: "header"
  required: true
  type: "string"

definitions:
  LearnerContentAssignmentActionRequest:
    type: "object"
    properties:
      assignment_uuids:
        type: "array"
        description: "List of assignment uuids"
        items:
          type: "string"
          description: "assignment uuid"
  PolicyAllocationRequestBody:
    type: "object"
    properties:
      learner_emails:
        type: "array"
        description: "Learner emails to whom LearnerContentAssignments should be allocated."
        required: true
        items:
          type: "string"
          description: "email of a learner"
      content_key:
        type: "string"
        description: "Course content_key to which these learners are assigned."
        required: true
      content_price_cents:
        type: "integer"
        description: "The price, in USD cents, of this content at the time of allocation. Must be >= 0."
        required: true

endpoints:
  v1:
    # /api/v1/policy-allocation/{policy_uuid}/allocate/
    subsidyAccessPolicyAllocation:
      post:
        description: "creates or updates allocated LearnerContentAssignment records for a requested list of user email addresses, 
          in the requested content_key and at the requested price of content_price_cents"
        operationId: "api_v1_policy_allocation_allocate_create"
        consumes:
          - "application/json"
        produces:
          - "application/json"
        parameters:
          - *auth_header
          - in: path
            name: policy_uuid
            type: string
            description: The uuid that uniquely identifies this policy record.
            required: true
          - name: "PolicyAllocationRequestBody"
            in: "body"
            description: "Contains learner emails, content keys and price"
            required: true
            schema:
              type: "array"
              items:
                $ref: "#/definitions/PolicyAllocationRequestBody"
        responses: *learner_content_assignment_allocate_responses
        x-amazon-apigateway-integration:
          responses: *apigateway_responses
          httpMethod: "POST"
          type: "http"
          requestParameters:
            integration.request.header.Authorization: "method.request.header.Authorization"
            integration.request.path.policy_uuid: "method.request.path.policy_uuid"
          uri: "https://${stageVariables.enterprise_access_host}/api/v1/policy-allocation/{policy_uuid}/allocate/"
    # api/v1/assignment-configurations/{assignment_configuration_uuid}/admin/assignments/
    learnerContentAssignmentListRequest:
      get:
        description: "Lists LearnerContentAssignment records, filtered by the given query parameters."
        operationId: "api_v1_assignment_configurations_admin_assignments_list"
        consumes:
          - "application/json"
        produces:
          - "application/json"
        parameters:
          - *auth_header
          - *assignment_configuration_uuid
          - in: query
            name: content_key
            type: string
            description: "The globally unique content identifier to assign to the learner.
              Joinable with ContentMetadata.content_key in enterprise-catalog."
            required: false
          - in: query
            name: content_key__in
            type: array
            description: "The globally unique content identifier to assign to the learner.
              Joinable with ContentMetadata.content_key in enterprise-catalog."
            required: false
            items:
              type: string
          - in: query
            name: learner_email
            type: string
            description: "Email of learner to assign content. Automatically scrubbed after 90 days."
            required: false
          - in: query
            name: learner_email__in
            type: array
            description: "Email of learner to assign content. Automatically scrubbed after 90 days."
            required: false
            items:
              type: string
          - in: query
            name: learner_state
            type: string
            enum: ["notifying", "waiting", "failed", "expired"]
            description: "Choose from the following valid learner states: notifying, waiting, failed, expired."
            required: false
          - in: query
            name: learner_state__in
            type: array
            description: "Choose from the following valid learner states: notifying, waiting, failed, expired."
            required: false
            items:
              type: string
              enum: ["notifying", "waiting", "failed", "expired"]
          - in: query
            name: lms_user_id
            type: integer
            description: "The id of the Open edX LMS user record with which this LearnerContentAssignment is associated.
              This may be null at time of creation."
            required: false
          - in: query
            name: lms_user_id__in
            type: array
            description: "The id of the Open edX LMS user record with which this LearnerContentAssignment is associated.
              This may be null at time of creation."
            required: false
            items:
              type: integer
          - in: query
            name: ordering
            type: string
            description: "Which field to use when ordering the results."
            required: false
          - in: query
            name: page
            type: integer
            description: "A page number within the paginated result set."
            required: false
          - in: query
            name: page_size
            type: integer
            description: "Number of results to return per page."
            required: false
          - in: query
            name: search
            type: string
            description: A search term.
            required: false
          - in: query
            name: state
            type: string
            enum: ["allocated", "accepted", "cancelled", "errored", "expired", "reversed"]
            description: "The current state of the LearnerContentAssignment. One of: 
              ['allocated', 'accepted', 'cancelled', 'errored', 'expired', 'reversed']"
            required: false
          - in: query
            name: state__in
            type: array
            description: "The current state of the LearnerContentAssignment. One of: 
              ['allocated', 'accepted', 'cancelled', 'errored', 'expired', 'reversed']"
            items:
              type: string
              enum: ["allocated", "accepted", "cancelled", "errored", "expired", "reversed"]
            required: false
        responses: *learner_content_assignment_list_remind_cancel_responses
        x-amazon-apigateway-integration:
          responses: *apigateway_responses
          httpMethod: "GET"
          type: "http"
          requestParameters:
            integration.request.header.Authorization: "method.request.header.Authorization"
            integration.request.path.assignment_configuration_uuid: "method.request.path.assignment_configuration_uuid"
            integration.request.querystring.content_key: "method.request.querystring.content_key"
            integration.request.querystring.content_key__in: "method.request.querystring.content_key__in"
            integration.request.querystring.learner_email: "method.request.querystring.learner_email"
            integration.request.querystring.learner_email__in: "method.request.querystring.learner_email__in"
            integration.request.querystring.learner_state: "method.request.querystring.learner_state"
            integration.request.querystring.learner_state__in: "method.request.querystring.learner_state__in"
            integration.request.querystring.lms_user_id: "method.request.querystring.lms_user_id"
            integration.request.querystring.lms_user_id__in: "method.request.querystring.lms_user_id__in"
            integration.request.querystring.ordering: "method.request.querystring.ordering"
            integration.request.querystring.page: "method.request.querystring.page"
            integration.request.querystring.page_size: "method.request.querystring.page_size"
            integration.request.querystring.search: "method.request.querystring.search"
            integration.request.querystring.state: "method.request.querystring.state"
            integration.request.querystring.state__in: "method.request.querystring.state__in"
          uri: "https://${stageVariables.enterprise_access_host}/api/v1/assignment-configurations/{assignment_configuration_uuid}/admin/assignments/"
    # api/v1/assignment-configurations/{assignment_configuration_uuid}/admin/assignments/remind/
    learnerContentAssignmentRemindRequest:
      post:
        description: "Send reminders to a list of learners with associated ``LearnerContentAssignment``
          record by list of uuids."
        operationId: "api_v1_assignment_configurations_admin_assignments_remind_create"
        consumes:
          - "application/json"
        produces:
          - "application/json"
        parameters:
          - *auth_header
          - *assignment_configuration_uuid
          - name: "LearnerContentAssignmentRemindRequest"
            in: "body"
            description: "Single or multiple assignment_uuids in the array"
            required: true
            schema:
              type: "array"
              items:
                $ref: "#/definitions/LearnerContentAssignmentActionRequest"
        responses: *learner_content_assignment_list_remind_cancel_responses
        x-amazon-apigateway-integration:
          responses: *apigateway_responses
          httpMethod: "POST"
          type: "http"
          requestParameters:
            integration.request.header.Authorization: "method.request.header.Authorization"
            integration.request.path.assignment_configuration_uuid: "method.request.path.assignment_configuration_uuid"
          uri: "https://${stageVariables.enterprise_access_host}/api/v1/assignment-configurations/{assignment_configuration_uuid}/admin/assignments/remind/"
    # api/v1/assignment-configurations/{assignment_configuration_uuid}/admin/assignments/cancel/
    learnerContentAssignmentCancelRequest:
      post:
        description: "Cancel a list of ``LearnerContentAssignment`` records by uuid"
        operationId: "api_v1_assignment_configurations_admin_assignments_cancel_create"
        consumes:
          - "application/json"
        produces:
          - "application/json"
        parameters:
          - *auth_header
          - *assignment_configuration_uuid
          - name: "LearnerContentAssignmentActionRequest"
            in: "body"
            description: "Single or multiple assignment_uuids in the array"
            required: true
            schema:
              type: "array"
              items:
                $ref: "#/definitions/LearnerContentAssignmentActionRequest"
        responses: *learner_content_assignment_list_remind_cancel_responses
        x-amazon-apigateway-integration:
          responses: *apigateway_responses
          httpMethod: "POST"
          type: "http"
          requestParameters:
            integration.request.header.Authorization: "method.request.header.Authorization"
            integration.request.path.assignment_configuration_uuid: "method.request.path.assignment_configuration_uuid"
          uri: "https://${stageVariables.enterprise_access_host}/api/v1/assignment-configurations/{assignment_configuration_uuid}/admin/assignments/cancel/"
    # api/v1/subsidy-access-policies/
    subsidyAccessPolicies:
      get:
        description: "Lists SubsidyAccessPolicy records, filtered by the given query parameters."
        operationId: "api_v1_subsidy_access_policies_list"
        consumes:
          - "application/json"
        produces:
          - "application/json"
        parameters:
          - *auth_header
          - in: query
            name: active
            type: boolean
            description: "Set to FALSE to deactivate and hide this policy. Use this when you want to disable redemption
              and make it disappear from all frontends, effectively soft-deleting it. Default is False (deactivated)."
            required: false
          - in: query
            name: enterprise_customer_uuid
            type: string
            description: The owning Enterprise Customer's UUID. Cannot be blank or null.
            required: true
          - in: query
            name: page
            type: integer
            description: A page number within the paginated result set.
            required: false
          - in: query
            name: page_size
            type: integer
            description: Number of results to return per page.
            required: false
          - in: query
            name: policy_type
            type: string
            description: The type of this policy (e.g. the name of an access policy proxy model).
            required: false
        responses: *learner_content_assignment_list_remind_cancel_responses
        x-amazon-apigateway-integration:
          responses: *apigateway_responses
          httpMethod: "GET"
          type: "http"
          requestParameters:
            integration.request.header.Authorization: "method.request.header.Authorization"
            integration.request.querystring.active: "method.request.querystring.active"
            integration.request.querystring.enterprise_customer_uuid: "method.request.querystring.enterprise_customer_uuid"
            integration.request.querystring.page: "method.request.querystring.page"
            integration.request.querystring.page_size: "method.request.querystring.page_size"
            integration.request.querystring.policy_type: "method.request.querystring.policy_type"
          uri: "https://${stageVariables.enterprise_access_host}/api/v1/subsidy-access-policies/"